Crosstech Impl Speckle Revit

crosstech-impl-speckle-revit

Quick Reference

Side A: Speckle (Base Objects)

Side B: Revit (Families, Parameters, Elements)

The Bridge: Speckle Revit Connector

Critical Warnings

NEVER expect round-trip parametric fidelity — elements sent from Revit return as DirectShapes, NOT as editable native families.

NEVER rely on speckle_type for BIM classification in Speckle v3 — it is ALWAYS Objects.Data.DataObject. Inspect properties.category instead.

NEVER assume hosted element relationships survive — doors/windows lose their wall-host association after Speckle transport.

NEVER omit reference point configuration — mismatched reference points between send and receive cause geometry displacement.

ALWAYS verify applicationId values before re-receiving — they control whether elements are updated or duplicated.

ALWAYS set the Detail Level (Low/Medium/High) before receiving — it controls tessellation quality of DirectShape geometry.

Send Pipeline: Revit to Speckle

Stage 1: Element Selection

Four selection strategies exist. ALWAYS choose based on project needs:

Stage 2: Element Unpacking

Complex elements are expanded into atomic objects:

• Curtain walls decompose into panels + mullions
• Stairs decompose into runs + landings + railings
• Groups are expanded into individual members

Stage 3: Conversion

The RevitRootObjectBuilder converts each Revit element:

1. Reads element geometry via Revit API GeometryElement
2. Extracts ALL parameters (Type + Instance) into nested dictionary
3. Resolves Family, FamilyType, and Category names
4. Generates displayValue meshes at the configured Detail Level
5. Assigns applicationId from Revit's UniqueId property

Stage 4: Caching

The RevitToSpeckleCacheSingleton prevents redundant conversion. Elements with unchanged geometry and parameters reuse cached Speckle objects. This is critical for large models (10,000+ elements).

Stage 5: Transport

Serialized objects are sent to the selected transport (ServerTransport for cloud, SQLiteTransport for local). The root object hash becomes the version reference.

Receive Pipeline: Speckle to Revit

Stage 1: Object Reception

Download and deserialize the root object and all children from the transport.

Stage 2: Type Mapping

The connector matches Speckle objects to Revit families/types:

ALWAYS use manual mapping when receiving from non-Revit sources (Blender, Rhino, ArchiCAD) — automatic mapping relies on Revit-specific naming conventions that other tools do not produce.

Stage 3: DirectShape Creation

When no matching native family exists, elements are created as DirectShapes:

• DirectShapes accept arbitrary solid/mesh geometry
• They belong to a Revit category (Walls, Generic Models, etc.)
• They have NO parametric behavior — geometry is frozen
• They CAN receive parameter values as custom shared parameters

Stage 4: Material Application

The RevitMaterialBaker creates or matches Revit materials:

• Maps Speckle RenderMaterial to Revit Material class
• Basic properties transfer: diffuse color, transparency, metalness
• Complex shader graphs do NOT transfer — only base color values

Stage 5: Group and Hierarchy

The RevitGroupBaker recreates organizational structure:

• Speckle Collections become Revit Groups
• Level assignments from levelProxies are restored
• Spatial hierarchy is approximated but NOT identical to original

Stage 6: Transaction Commit

ALL Revit modifications are wrapped in a single Transaction:

// Speckle connector internal pattern
using (Transaction t = new Transaction(doc, "Speckle Receive"))
{
    t.Start();
    // ... create DirectShapes, apply materials, set parameters ...
    t.Commit();
}

If any element fails, the entire transaction rolls back. Check the Speckle log for conversion warnings.

Round-Trip Data Integrity

What SURVIVES Revit to Speckle to Revit

What is LOST or DEGRADED

Update-in-Place Behavior

When receiving from the same source a second time:

1. Connector reads applicationId of each incoming object
2. Matches against applicationId values of existing DirectShapes in the project
3. Match found: Updates geometry and parameters of existing element
4. No match: Creates a new DirectShape

This preserves dimensions, tags, and annotations attached to previously received elements. ALWAYS use the same Speckle model/branch for iterative workflows.

Reference Point Configuration

ALWAYS use Survey Point when exchanging data between Revit and QGIS/GIS tools via Speckle.

ALWAYS use the same reference point setting for both send and receive operations in a round-trip workflow.

Speckle .NET SDK: Programmatic Access

For automated pipelines bypassing the UI connector:

using Speckle.Core.Api;
using Speckle.Core.Credentials;
using Speckle.Core.Transports;
using Speckle.Core.Models;

// Authenticate
var account = AccountManager.GetDefaultAccount();
var client = new Client(account);

// Create transport
var transport = new ServerTransport(account, "stream-id-here");

// Send a Base object
var myObject = new Base();
myObject["category"] = "Walls";
myObject["parameters"] = parametersDictionary;

string objectId = await Operations.Send(myObject, new[] { transport });

// Create a version (commit)
var commitId = await client.CommitCreate(new CommitCreateInput
{
    streamId = "stream-id-here",
    objectId = objectId,
    branchName = "main",
    message = "Automated wall export"
});

Linked Model Support

The connector supports sending linked Revit models:

• Each linked model creates a separate DocumentToConvert context
• A transformation matrix positions the linked model relative to the host
• applicationId values are modified with a transform hash to distinguish instances of the same linked model at different positions
• ALWAYS verify that linked model positions are correct after receiving — transformation stacking can introduce drift

Version Compatibility Matrix

ALWAYS match the connector version to the Revit version — a .NET 4.8 connector NEVER works in Revit 2025+.

Reference Links

• references/methods.md — API methods for send/receive, type mapping, parameter extraction
• references/examples.md — Working code examples for common Speckle-Revit workflows
• references/anti-patterns.md — What NOT to do at the Speckle-Revit boundary

Official Sources

• https://speckle.guide/user/revit.html
• https://speckle.systems/tutorials/
• https://github.com/specklesystems/speckle-sharp
• https://github.com/specklesystems/speckle-sharp-connectors
• https://speckle.guide/dev/dotnet.html