SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillscrosstech-impl-speckle-revit

crosstech-impl-speckle-revit

General & other

View repository

Updated 10-15 22:17

About this skill

crosstech-impl-speckle-revit

Quick Reference

Side A: Speckle (Base Objects)

Concept Description
Base Root class for all Speckle objects; hash-based immutable identity
speckle_type Type discriminator — in v3 ALWAYS Objects.Data.DataObject for BIM elements
displayValue Mesh geometry for rendering; the atomic visual unit
parameters Nested dictionary holding Type Parameters and Instance Parameters
applicationId Secondary ID from the host application; enables update-in-place
Collection Hierarchical grouping with name, collectionType, elements
Proxy Collections levelProxies, colorProxies, renderMaterialProxies at root level

Side B: Revit (Families, Parameters, Elements)

Concept Description
Family Template defining geometry and behavior (e.g., M_Single-Flush)
Family Type Specific parametric variant of a Family (e.g., 0915 x 2134mm)
System Family Built-in families: Walls, Floors, Roofs, Ceilings, Stairs
Instance Parameter Per-element values (Base Offset, Mark, Comments)
Type Parameter Shared across all instances of a type (Width, Fire Rating)
DirectShape Geometry-only container; no parametric intelligence
Workset Collaboration partition; NOT preserved through Speckle
ElementId Revit's internal integer identifier; unstable across sessions

The Bridge: Speckle Revit Connector

Aspect Detail
Directionality Bidirectional with asymmetric fidelity
Send granularity View-based, selection-based, category-based, or workset-based
Receive output DirectShapes (default) or mapped native families
Parameter handling ALL parameters extracted; nested Type/Instance structure
Update mechanism applicationId matching enables update-in-place
Reference points Internal Origin, Project Base Point, or Survey Point

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:

Strategy Use When API Entry Point
View-based Sending visible elements from a specific view Active view filter
Selection set Sending hand-picked elements Current selection
Category filter Sending all elements of specific categories Category list
Workset filter Sending by collaboration partition Workset list

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:

Mapping Mode Behavior
Automatic Matches by Category + Family + Type name strings
Manual Presents a mapping table for user assignment

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

Data Fidelity Notes
Geometry shape High Tessellated mesh; Detail Level affects quality
Parameter values High Both Type and Instance; stored in nested dict
Material assignments Medium Basic color/opacity; no PBR shader graphs
Object grouping Medium Collections approximate Revit groups
applicationId Exact Enables update-in-place on re-receive
Category assignment High Revit category preserved as string

What is LOST or DEGRADED

Data Impact Why
Parametric intelligence Critical Elements return as DirectShapes, not editable families
System family behavior Critical Walls, floors, roofs lose join/extend/attach logic
Hosted element relationships High Door-in-wall, window-in-wall links are flattened
Workset assignments High Not tracked through Speckle transport
Design options High Not represented in Speckle schema
Schedule grouping Medium Parameter grouping for schedules is lost
Phase information Medium Created/demolished phase data not preserved
Detailed edge profiles Low Swept profiles simplified to mesh

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

Setting Coordinate Origin Use When
Internal Origin Revit's absolute (0,0,0) Default; intra-Revit exchange
Project Base Point User-defined project origin Aligning with site coordinates
Survey Point Real-world survey coordinates Exchanging with GIS/geospatial tools

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

Revit Version .NET Runtime WebView Technology Speckle Connector
2022-2024 .NET Framework 4.8 CefSharp Speckle 2.x / 3.x
2025-2026 .NET 8.0 WebView2 Speckle 3.x

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

Reference Links

Official Sources