This article describes in detail the attributes system and its mechanisms. For a quick overview of the various use cases for ShapeDiver attributes, check out the Attributes Cheat Sheet.
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, it often happens that the data coming to Grasshopper contains more information than what the standard Grasshopper types contain. As an 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 of them 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 of the objects in the resulting file.
The above examples are very specific, 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 in it. See below a first simple example of creating an attribute object containing a single key/value pair and injecting this attribute in a mesh. At the end, we verify that the attribute is succesfully stored in the mesh by extracting it back and reading its contents:
It is also possible to visualized 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 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:
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.
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.
Read more about each component of the plugin that supports reading, writing and manipulating attributes.