Attributes

This article describes in detail the attributes system and its mechanisms. Check out the Attributes Cheat Sheet for a quick overview of the various use cases for ShapeDiver attributes.

Introduction

One of the main functions of the ShapeDiver plugin is to turn Grasshopper definitions into online interfaces where users can remotely send data (parameters, geometry, images, text files, etc…) and receive data (3d visualization in the online viewer, direct data outputs, exported CAD files, etc…).

For the time this data flows through the Grasshopper definition, it is represented through one of the many data types that Grasshopper can handle: multiple geometry and primitive types as listed in the Params category of Grasshopper.

However, the data coming to Grasshopper often contains more information than what the standard Grasshopper types contain. For example, when using the Import Geometry component to import a set of curves from a DXF file, the component will send back a list of objects of the Curve type in Grasshopper. But the DXF file does not only contain curves: each might have a name, a layer, and a color, for example. Conversely, when exporting a set of curves using the Download Export component, one might want to assign the same properties for each object in the resulting file.

The above examples are concrete, but in practice, there are various applications where injecting some additional information to the inputs and outputs of an application is very useful. Each object could contain its own material description for the viewer or even custom information that the ShapeDiver viewer can visualize for analysis purposes.

The Attributes system

In order to allow such applications, the ShapeDiver plugin comes with its own Attributes system. In practice, it means that if you have the ShapeDiver plugin installed in Grasshopper, every geometry and primitive supported by the plugin can be augmented by injecting an Attributes Object. See below a first simple example of creating an attribute object containing a single key/value pair and injecting this attribute in a mesh. In the end, we verify that the attribute is successfully stored in the mesh by extracting it back and reading its contents:

It is also possible to visualize stored attributes in objects of the canvas by hovering over them or connecting them to a text panel:

There are two types of attributes: reserved attributes and custom attributes. Read more about each of these types below.

Reserved attributes

Reserved attributes are attributes which have a predefined meaning when creating a ShapeDiver application. As an example, the name attribute has a specific meaning when importing and exporting files from ShapeDiver: it will map to the native name property of each file type that supports it. For example, 3dm and dxf files support naming objects. The objects imported from these file types come in Grasshopper with a predefined name attribute corresponding to their name in the original document. Conversely, defining a name attribute in geometry before it is exported will automatically set the native name property for the object in the exported document. See below an example application where a 3dm file is imported and the names of objects are changed to add the SD_ prefix before the file is exported again:

Reserved attributes do not map to meaningful properties in all environments. Not all file types support naming or materials for example, therefore name and material attributes are ignored in those cases. Additionally, some attributes, such as the transform attribute, only make sense in the context of the ShapeDiver Display components used by the online viewer to display geometry.

Find in the cheat sheet how the list of reserved attributes currently supported (the list will keep growing in the future) behave when used with the various I/O components of the plugin.

Helper components for reserved attributes

Since reserved attributes are likely used more frequently, the ShapeDiver plugin comes with some helper components which automatically build them without having to used the Construct Attributes component. Consider the example below where the Export Attributes component provides a condensed way to inject all typical properties one might want to set before exporting files:

Custom attributes

Using the Construct Attributes and Inject Attributes components, any set of key/value pairs can be injected in Grasshopper objects. This allows for much flexibility regardless of which client the data is consumed (online viewer, Rhino, in the future many more…). Below are two examples of how custom attributes are leveraged in the viewer and when working with 3dm files.

Custom attributes and the attribute visualization mode

In order to visualize custom attributes in the viewer, one needs to use the ShapeDiver Output component, which allows to output enriched data, as opposed to the ShapeDiver Display components which only support plain geometry and do not retain stored attributes.

There are two ways custom attributes can be manipulated in the viewer. First of all, every custom attribute (like reserved attributes) can be accessed through the viewer API and use for any purpose by a web application. Additionally, the model view page on the ShapeDiver platform includes an attribute visualization panel which lets users switch from the rendered mode. In the attribute visualization mode, it is possible to select any number of attributes for visualization and define gradient color schemes to create analysis models.

Read more about the attribute visualization mode on the platform.

Custom attributes and 3dm files

When importing and exporting 3dm files, there is an explicit mapping between ShapeDiver attributes and Rhino Attribute User Text entities.

Attributes and desktop clients

It is possible to connect the ShapeDiver platform with a range of desktop clients, in order to exchange data and geometry between local software and a ShapeDiver model. In a way similar to the usage of attributes when importing and exporting files from a model, the Attributes system to include metadata about the exchanged objects such as document and object properties.

Read more in the Desktop clients section about this use case and how attributes can be used in each of the desktop clients supported by ShapeDiver.

Supported Attribute types

You might have noticed in the table of reserved attributes that not only Text values are supported as attributes, but also various other data types (in the table, Text, Number, Color, ShapeDiver Material, Transforms object). As a matter of fact, most of the data types in Grasshopper are supported as attributes, and can be injected in any object type as well. As an example, it is possible to inject a mesh attribute in a Text. Of course, not all use cases are justified, but the feature has been conceived as flexible for future uses, in accordance with the sdTF file format we use for transferring data to and from our servers.

Plugin components

Read more about each component of the plugin that supports reading, writing and manipulating attributes.