# Speckle Impl Rhino Grasshopper

> >

- **Type:** Skill
- **Install:** `agentstack add skill-impertio-studio-speckle-claude-skill-package-speckle-impl-rhino-grasshopper`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [Impertio-Studio](https://agentstack.voostack.com/s/impertio-studio)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [Impertio-Studio](https://github.com/Impertio-Studio)
- **Source:** https://github.com/Impertio-Studio/Speckle-Claude-Skill-Package/tree/master/skills/source/speckle-impl/speckle-impl-rhino-grasshopper

## Install

```sh
agentstack add skill-impertio-studio-speckle-claude-skill-package-speckle-impl-rhino-grasshopper
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# speckle-impl-rhino-grasshopper

## Quick Reference

### Platform Requirements

| Requirement | Value |
|-------------|-------|
| Rhino versions | 7, 8 (8.9+ recommended) |
| OS | Windows only |
| Connector bundle | Rhino + Grasshopper (single installer) |
| Authentication | Via Speckle Desktop Service |

### Rhino Data Schema

```
File > Layer > Sublayer > Objects
```

### Object Types in Rhino

| Type | Description | Speckle Mapping |
|------|-------------|-----------------|
| Geometry Objects | Point, Line, Mesh, Brep — standalone primitives | Geometry Objects (no `properties`, no `displayValue`) |
| Block Instances | References to block definitions with transform | Instance Objects (`definitionId` + 4x4 `transform`) |
| Data Objects | Objects with attached user data | DataObject (`properties` + `displayValue`) |

### Proxy Types Used by Rhino

| Proxy | Purpose |
|-------|---------|
| RenderMaterial | Color (RGB), opacity, metallic, roughness |
| Color | Hex color assignments (#RRGGBB) |
| Group | Functional grouping of objects |
| Definition | Block geometry stored once, reused by instances |

### 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:

| Content Type | Details |
|--------------|---------|
| Geometry | All visible geometry types (Point, Line, Curve, Mesh, Brep, Surface, Extrusion) |
| Hatches | Pattern fills |
| Text | Text objects and annotations |
| Blocks | Block definitions and instances |
| User strings | Custom key-value properties attached to objects |
| Named views | Perspective views only (parallel projections excluded) |
| Layers | Full layer hierarchy preserved as Collections |

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

### Publishing Settings

| Setting | Effect |
|---------|--------|
| Layer filter | Publish only objects on selected layers |
| Visualization properties | Include vertex normals, colors, texture coordinates (increases file size) |

### Loading into Rhino

| Data | Behavior |
|------|----------|
| Geometry | Loads as native Rhino geometry (Point, Curve, Mesh, Brep) |
| Text | Loads as text objects |
| Blocks | Loads as block definitions + instances |
| Render materials | Preserved and applied |
| Colors | Preserved and applied |
| Names | Preserved as object names |
| Custom properties | Loaded as user strings |
| Named views | Created automatically (NEVER overwrites existing views with same name) |

### 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

| Component | Purpose | Notes |
|-----------|---------|-------|
| **Sign-In** | Account authentication | Required before any publish/load |
| **Speckle Model URL** | Project/model selection | Right-click to switch accounts |

#### Publishing Workflow

| Component | Purpose | Notes |
|-----------|---------|-------|
| **Create Collection** | Organize objects into hierarchical collections | Maps to Rhino layers. Supports nesting via TAB+pipe. Empty inputs excluded automatically. |
| **Publish** | Send Collection + Model URL to server | Requires a Collection and a Model URL input |
| **Create Properties** | Create key-value property dictionaries | Supports: strings, numbers, booleans, vectors, planes, lists, nested properties |
| **Speckle Properties Passthrough** | Alternative property creation | Three modes: Merge (default), Remove, Replace |

#### Loading Workflow

| Component | Purpose | Notes |
|-----------|---------|-------|
| **Load** | Fetch model from server | Latest version by default, or specific version |
| **Query Objects** | Retrieve flattened list of all objects | Expandable outputs filter by geometry type |
| **Collection Selector** | Display full sub-collection paths | Search patterns: `?` (single char), `` (ends with), `;` (multiple patterns) |
| **Expand Collection** | Traverse hierarchy one level at a time | Use iteratively for deep hierarchies |
| **Deconstruct** | Access individual object fields | Returns field names, values, and types |

#### Object Manipulation

| Component | Purpose | Notes |
|-----------|---------|-------|
| **Speckle Geometry Passthrough** | Add metadata to geometry | Accepts native GH geometry or existing Speckle Geometry. Adds: Name, Properties, Color, Material |
| **Block Definition Passthrough** | Create block definitions | Input: geometry list. Output: reusable definition |
| **Block Instance Passthrough** | Create block instances | Input: definition + transform matrix |
| **Data Object Passthrough** | Create Data Objects | Input: geometry list + properties dictionary |
| **Filter Objects** | Filter loaded objects | Filter by: name, property keys, material name, Application ID, Speckle ID |

### 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](references/methods.md) — Grasshopper component signatures and Rhino connector API
- [references/examples.md](references/examples.md) — Working workflow examples for publish, load, and round-trip
- [references/anti-patterns.md](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

## Source & license

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

- **Author:** [Impertio-Studio](https://github.com/Impertio-Studio)
- **Source:** [Impertio-Studio/Speckle-Claude-Skill-Package](https://github.com/Impertio-Studio/Speckle-Claude-Skill-Package)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-impertio-studio-speckle-claude-skill-package-speckle-impl-rhino-grasshopper
- Seller: https://agentstack.voostack.com/s/impertio-studio
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.