speckle-impl-rhino-grasshopper

speckle-impl-rhino-grasshopper

Quick Reference

Platform Requirements

Rhino Data Schema

File > Layer > Sublayer > Objects

Object Types in Rhino

Proxy Types Used by Rhino

Critical Warnings

NEVER attempt to create native BIM elements (Revit walls, beams, columns) from Grasshopper. Grasshopper can ONLY create Geometry Objects, Block Objects, and Data Objects. When loaded into Revit, these ALWAYS become Direct Shapes.

NEVER expect parallel projection views to publish. Rhino and Grasshopper ONLY publish perspective named views. Parallel projections are silently excluded.

NEVER rely on Grasshopper parameter GUIDs for change tracking. Grasshopper generates new GUIDs on every solve cycle, breaking Speckle's change tracking. ALWAYS use passthrough nodes to mutate existing loaded objects.

ALWAYS use Rhino 8.9+ when working with Rhino 8. Earlier 8.x versions have known framework issues with the Speckle connector.

Rhino Connector

Publishing from Rhino

The Rhino connector publishes the following content:

Each published object includes: name, color, render material, and user strings.

Publishing Settings

Loading into Rhino

User Strings Round-Trip

User strings are the mechanism for custom property transfer in Rhino:

1. Publish: User strings attached to Rhino objects appear in properties on the Speckle server.
2. Load: Properties from Speckle objects are written back as user strings on received Rhino geometry.

This round-trip works for Rhino-to-Rhino workflows. Properties from other connectors (Revit parameters, Tekla report data) also load as user strings in Rhino.

Grasshopper Connector

Component Inventory

Authentication and Configuration

Publishing Workflow

Loading Workflow

Object Manipulation

Three Object Types in Grasshopper

1. Geometry Objects

• Single selectable elements
• Cast native Grasshopper geometry directly (Point, Curve, Mesh, Brep, Surface)
• Baking preserves: layer path, name, color, material, properties as user strings
• Use Speckle Geometry Passthrough to attach metadata

2. Block Objects

• Definitions: Geometry collections created via Block Definition Passthrough
• Instances: Placement references created via Block Instance Passthrough (definition + transform)
• Mirror native Rhino block structure
• ALWAYS create the definition first, then create instances that reference it

3. Data Objects

• Groups of geometries with rich property dictionaries
• Used for BIM/structural/civil workflows received from Revit, Navisworks, IFC, Archicad, Civil 3D, Tekla, ETABS
• Cast to single geometry ONLY when containing exactly one piece of geometry
• NEVER cast a Data Object with multiple geometries to a single geometry — this silently drops geometry

Collection Nesting

Create nested collections using TAB+pipe naming:

Collection "Architecture"
  ├── Sub-collection "Walls"    (name: "Architecture | Walls")
  ├── Sub-collection "Floors"   (name: "Architecture | Floors")
  └── Sub-collection "Roofs"    (name: "Architecture | Roofs")

The pipe character (|) preceded by TAB creates hierarchy levels. ALWAYS use this pattern for organizing published data from Grasshopper.

Property Creation

Use Create Properties to build property dictionaries:

Key inputs:     "height", "material", "load_bearing"
Value inputs:   3.5,      "concrete",  true

Supported value types: strings, numbers, booleans, vectors, planes, lists, nested property dictionaries.

ALWAYS attach properties via Create Properties or Speckle Properties Passthrough BEFORE publishing. Properties cannot be added after publish.

Block Handling

Publishing Blocks from Rhino

1. Block definitions are stored as Definition proxies at the root Collection level
2. Each block instance becomes an Instance Object with definitionId + 4x4 transform matrix
3. The definition geometry is stored once; instances reference it (deduplication)

Creating Blocks in Grasshopper

Step 1: Create geometry list → Block Definition Passthrough → definition
Step 2: definition + transform → Block Instance Passthrough → instance
Step 3: instance → Create Collection → Publish

Loading Blocks

• Blocks load as native Rhino block definitions + instances
• Nested blocks are supported (definitions referencing other definitions)
• Transform matrices are applied on load to position instances

Change Tracking in Grasshopper

The Problem

Grasshopper parameters generate new GUIDs on every solve cycle. Speckle uses applicationId for change tracking. New GUIDs mean Speckle treats every solve as entirely new objects — no updates, only additions.

The Solution

1. Create objects once and publish
2. Load the published model back into Grasshopper
3. Use passthrough nodes to mutate the loaded objects (preserves applicationId)
4. Publish the mutated objects

This preserves applicationId across versions, enabling proper change tracking and version comparison.

For New Models

ALWAYS follow this sequence for models that will be updated over time:

1. Create initial geometry and properties
2. Publish to Speckle
3. Load the published version back
4. Use passthrough nodes for ALL subsequent modifications
5. Re-publish

Reusable Components

Teams can create standardized User Objects (.ghuser files) with predefined:

• Naming conventions
• Property structures
• Collection hierarchies
• Publishing configurations

Distribute .ghuser files to team members for consistent project delivery across Grasshopper definitions.

Cross-Connector Behavior

Rhino to Revit

• Rhino geometry → Revit Direct Shapes (ALWAYS)
• User strings → NOT imported into Revit (Revit does not load custom properties)
• Blocks → Direct Shapes or Families (with "Receive Blocks as Families" setting in Revit)
• Named views → 3D views in Revit

Revit to Rhino

• RevitObjects → Geometry with properties as user strings
• Revit parameters → Rhino user strings (readable, editable)
• Material quantities → User string properties
• Level associations → User string properties

Grasshopper to Revit

• Geometry Objects → Direct Shapes
• Block Objects → Direct Shapes or Families
• Data Objects → Direct Shapes
• NEVER native BIM elements — this is a fundamental limitation

Reference Links

• references/methods.md — Grasshopper component signatures and Rhino connector API
• references/examples.md — Working workflow examples for publish, load, and round-trip
• references/anti-patterns.md — What NOT to do, with WHY explanations

Official Sources

• https://docs.speckle.systems/connectors/rhino/rhino.md
• https://docs.speckle.systems/connectors/grasshopper/grasshopper.md
• https://docs.speckle.systems/connectors/grasshopper/grasshopper-objects.md
• https://docs.speckle.systems/connectors/grasshopper/grasshopper-collections.md
• https://docs.speckle.systems/connectors/grasshopper/grasshopper-properties.md
• https://docs.speckle.systems/connectors/grasshopper/grasshopper-recommendations.md
• https://docs.speckle.systems/developers/data-schema/connectors/rhino-schema.md