home / docs / speckle user data utils

Posted on Tue, Apr 4, 2017 | 3 min read


Before you begin:

Download the custom user data utils from here: https://github.com/didimitrie/SpeckleUserDataUtils/tree/dev/releases. They are no longer bundled with the main Speckle Sender Receiver distribution, sorry!

To use with Speckle, make sure you go through the installation guide.

Introduction

The Speckle User Data Utilities deliver the “Rich” in the “Data Rich Design”. Similar to Elefront and other plugins that I might not know of, they allow you to easily define and attach a set of properties to geometry objects.

Objects with attached user data, if baked, will not loose it. As such, you can reference them again in Grasshopper and you will be able to retrieve that user data.

Furthermore, you can even send them through the Speckle Sender! When they come out on the other side, in a Speckle Receiver, they will have said user data attached to them.

In the background they work with Rhino’s ArchivableDictionary class.

They are extremly simple to use.

Creating Custom Properties

spk

The takeaways:

  • the input parameter name becomes the object’s key
  • the value of the input parameter becomes the object’s value

Nested Properties: Turtles All The Way Down

You can store three types of data: Numbers, Strings and Other Custom Properties.

spk

This allows you to easily create nested properties and store object information in logical groups that you can create to suit your specific project needs. It’s up to you.

Attaching Properties To Geometry

spk

Using the Set User Data component, just plug in the objects you want attach data to and created properties.

Baking User Data

If you bake objects in Rhino with user data attached to them it will be serialised: when you reference them back into Grasshopper, you will be able to extract that user data.

Getting Properties From Geometry

spk

Using the Get User Data component, plug in the objects you want to extract the user data from and get out the dictionaries.

Once you got the User Data, use the Expand User Data to, well, get the properties out again. Note that if you use nested properties you will need to Expand User Data the respective nested property too.

spk You can now filter your objects based on their properties using standard Grasshopper functionality.

Exporting

You have two options to export them: JSON and CSV.

JSON Strings

The most faithful representation. Straightforward, and nothing complicated:

[
  {
    "type": "side_panel",
    "centre": "0.0, -8.0, 20.0",
    "dist_attractor": 13.83970326936719,
    "scale_factor": 0.53810463458171542,
    "normal_vector": {
      "x": -1.4791141972893965E-31,
      ...
    }
  },
  {
    "type": "hex_panel",
    "scale_factor": 0.38469562983428035,
    "material": "reddish-like_glossy",
    "otherProperty": { ... }
  },
  {...}
]

Note that you always get out an array of json objects.

CSV

When exporting to CSV, the JSON structure is essentially “flattened”. First row will always contain all the property keys. Following there’s one row per object, with null values inserted where they don’t correspond. Let’s say you have the follwing UDs:

[
    {
        X: 42,
        Y: {
            nested_1: "hello",
            nested_2: "world"
        }
    },
    {
        random_prop: 123
    }
]

This will result in the following csv file:

ROW 0: X, Y.nested_1, Y.nested_2, random_prop
ROW 1: 42, hello, world, null
ROW 2: null, null, null, 123

Baking and Referencing

As mentioned above, if you bake your smart objects into Rhino proper, you will be able to retrieve the user data when you reference them again in grasshopper.

Sending via Speckle

Objects that have user data attached to them can be sent through the Speckle Sender without loosing their “smartness”: the properties will remain attached to the object, and in the near future, you will be even able to directly query the Speckle Server based on them. Neat, no?

For a tutorial on how to send data via Speckle, check this tutorial out!

Having trouble? Found a bug? Have a question? Join the discussion below our join our slack channel.