Once you've used Speckle in Grasshopper or Dynamo for a while you'll may start to realise that, if the data you're sending is too complex, those DataTrees and Nested Lists are not the most ideal way to share your data, as the actual meaning of those structures does not get shared along. Let's start fixing that by creating Speckle objects to organise and label our data.

Prerequisites

To follow along with this tutorial, you will need to register with Speckle and install the required connectors 🔌. It takes less than 3 minutes!

For a comprehensive overview of this connector, check our docs 📚!

Your First Speckle Object

Imagine you have a point and a text message you want to send together. Initially, you may be tempted to join both values into a list like so:

In grasshopper, it's common to merge things together like this.

This will work and, initially, there is nothing wrong with doing so. But, notice that whoever receives this data will have to know (or remember!) what each of these items represent, and how are they ordered. The problem increases when you have many points in different structures:

Just one message, many points. Not exactly what we were hoping for (one message per point)

To fix this, add a new Create Speckle Object node to your canvas. This is a variable input node, which allows you to modify the inputs at will (and its names!). Add two inputs and change their names to location and message respectively. It should look like so 👇🏼

Your first speckle object! Notice the output is a Base object.

Connect the values as shown and the result will be a single Base object. This object holds both the point and the text message (similar to our first attempt)

The object and its expanded values. We'll cover this a bit later.

List values

We just created our first Speckle Object, whose values were all single items, meaning: a single point and a single message got stored together.

This behaviour is similar to the Python and C# scripts, where you must select the Access type for each input.

Notice the difference in output items when each access type is used

Imagine now that, instead of attaching each message to a point, we wanted to attach a message to a group of points. We could just change the location access to list to obtain one custom speckle object per list of points, each with a message attached to it.

Notice the output has reduced from 10 lists of 10 objects, to 10 lists of 1 object each.

Choosing the wrong type of access for your inputs will most likely result in data duplication. Choose wisely!

Optional values

It is fairly common for your custom objects to require optional inputs. Take for example a conceptual wall: It may, or may not, contain windows, doors, etc... but still be a valid wall.

If we were to require all inputs on every case, it would be impossible to cover all the custom data needs of every user. Hence, the optional menu item is available to let the component know if an input is not required.

Bypassing the required input warning by setting an input as optional

Inspecting Speckle Objects

Once you have a Speckle object, you may want to have a peek inside. You can do this in several ways:

Expand the object

Use the Expand Speckle Object node to retrieve all the keys and values of a given Speckle Object. This is, conceptually, the opposite action than Create Speckle Object.

Connect any Speckle object to this node and it will expose all it's values alphabetically ordered by key.

Expanding an object is the opposite of creating it. It will expose all properties of that object as outputs.

We do our best to keep your Grasshopper wires in place, so if you had an existing connection and your object changes, we will preserve that old output to prevent loosing those connections. To remove this, just disconnect it manually and recompute.

Keeping connections from outputs to preserve user intent.

Get individual values

You can also get individual values from a Speckle object using the Get Speckle Object value by key node. This allows you to obtain just the values that you need from objects that contain many keys, and keep your Grasshopper definitions lean.
To do this, just plug in a Speckle object and a list of keys into the component. The output will be the value for that key when available, or null if the key did not exist in the object.

You can fetch multiple values at once. If the property doesn't exist it will return null

Extending Speckle Objects

We've covered how to create and inspect custom Speckle objects, but what about adding new information after the object was created? You can also do this easily with the `Extend Speckle Object` node.

Extend speckle node, as it appears when created (left) and after adding custom inputs (right)

Just as the Create Speckle Object, this node is also a variable input node. The only difference being that its first input is the object you want to add information to.

Adding new information to an object

You can overwrite values too! You'll see a warning on the node to notify you

Overriding the location value with Extend Speckle Object

Nesting Speckle Objects

Nested speckle objects are also a thing!! No need to sweat, just plug Base objects as inputs of other Base objects.

Imagine a building that is comprised of a location and some floors. Each floor would contain a height, a name, and a list of units; and each unit contains the area, type and number of rooms.

You could replicate this type of structure in Speckle like so 👇

Conceptual building using nested speckle objects to organise, categorise and label the data.

If you receive this structure from someone else, you just need to expand it until you reach the data you need 👇🏼

Doing the inverse operation: starting from the "building" and expanding down to the unit values.

Conclusion

We hope you enjoyed this tutorial and found it useful!

Speckle is an Open Source project and we really ❤️ feedback, so if you have any questions, comments, critiques, or praises please let us know on our community forum.