Gumball Input

Use the Gumball Input component of the plugin to let users of your Apps (and models in the future) transform objects in the online viewer by manipulating a gumball. In Grasshopper, information about the transformation state (i.e., which objects were transformed and their associated transformation) can be retrieved as input and used to drive the parametric definition.

Overview

The Gumball Input component needs to be set up along with a glTF 2.0 Display component, which contains one or several objects with a set name attribute. Read more about how to properly set up objects for filtering here.

The component contains two outputs:

The “Names” output sends the name of the objects that were selected by users in the online viewer. When working locally, the transformation context does not exist, but one can use the “Local test data” component option to simulate the tranformations and test the contextual logic inside Grasshopper (see section below).
The “Transforms” output sends the list of transformations, where each item in the list matches the corresponding item of the “Names” output.

Component options

Name filters: use this option to define one or several name filters specifying which displayed geometry should be selectable (clickable) in the viewer . Read more about name filters in this article.
Handles toggles: the next three options of the component allow to toggle various handles for the gumball: the translation handles, the rotation handles and the scaling handles. Toggles exist for handles in all three directions of the object’s construction plane. By default, the translation and rotation handles are all enabled and the scaling handles are disabled.
Hover: whether or not a mouse hovering effect should be displayed on the objects that can be transformed in the scene before they are selected.
Local test data: Simulate the transformation of one or several objects in the viewer by entering their name(s) in this field. These values are only meant for local testing and will be ignored after uploading the definition to the platform. For each specified name, the “Transforms” output of the component will output an identity transformation.

Detailed workflow considerations

In most cases, when using the Gumball Input component, the transformations applied by users of the online App need to be applied to the geometry in Grasshopper by means of the “Transforms” output of the component. It is the responsibility of the definition to ensure this is done. In this section, we detail the process in a simple case before considering most intricate ones.

Always use the transform attribute

Consider the case of a definition with a single box that users of the App should be able to transform. Using the filtering workflow described here, we need to inject a name in the box and send it to a glTF 2.0 Display component:

In order to make the box selectable, we add a Gumball Input component with the name filter set to MyDisplayComponent.box (the name of the component followed by the name of the object):

At this point, after uploading the definition to ShapeDiver, it will already be possible to transform the box using the gumball. However, since the transformation in the component is not applied in the definition, the box will always go back to its initial position (and scale) after triggering a computation of the model. While this might be the desired behaviour in some cases, in the majority of them one will expect the box to keep the transformation that was defined in the App.

In order to do this, one might want to directly apply the transformation from the component to the object, as follows (in order to test locally, make sure to add the name MyDisplayComponent.box in “Local test data”):

Unfortunately, this method will not work, for multiple reasons.

First, remember that your local test data will not exist after uploading the definition to ShapeDiver, therefore no transformation is returned by the component by default. One should instead test the existence of a transformation from the Gumball Input, and if none are defined, send the identity transformation instead:

The second reason is a little more intricate, but fundamental for understanding how the App and the component work together. If one applies the transformation directly to the object, the transformation itself becomes part of the model, and the information is lost in the App. This means that, when using the gumball a first time, the transformation will be applied correctly. But in the following gumball changes, previous transformations will be forgotten, and only the last transformation will be applied.

In order to keep track of the previous transformations that were already applied, one should instead attach them as an attribute of the object. That way, the App can read the information and apply it in the viewer before further interactions, therefore compounding all interactions during a configuration session in the App. This can be done as follows:

Download this first minimal Gumball example.

Considerations when several objects are selectable

A single display component can include several objects with various name attributes:

However, not all objects are necessarily transformed in the App; the user might have only used gumball on one or several but not all of these objects. In that case, the Gumball Input component only returns the list of transformed objects:

It is therefore important to have a clear naming scheme and robust logic in Grasshopper to make sure transform attributes are applied correctly to the objects they belong to. In the following example, we implement a simple logic that creates an Identity transformation for all objects in the name filter list, and then replaces some of these identity transformations with the ones sent by the Gumball Input, making sure all objects get the correct transformation data:

This is only a suggestion for organizing the transformation data; other methods are, of course, possible.

Download the full tutorial example for multiple box transformation.

Transforming dynamic objects

Both examples above deal with objects that are transformed solely through the gumball interactions. In other words, the objects associated with the Gumball inputs only pass through the Grasshopper definition before, at the end, they are injected with a name and transform attributes and displayed in the viewer.

While these examples cover many use cases, more complex applications might use the transformation to further modify the dragged object itself in the process. Consider the following example:

Documentation in progress! This more complex example will be ready soon.