Description of the model parameters

Introduction

The ShapeDiver viewer and API provide an interface to interact with the parameters of the Grasshopper models uploaded on the platform. These parameters usually represent physical dimensions (length, height, sizes of all kinds...), other physical properties (materials, colors, shape, etc...), various options and modules (add, remove or replace specific parts, change their number...) and much more.

Each model parameter has a type and a set of properties describing it more accurately, according to the original parameter created in Grasshoppper. One can make an analogy between those parameters and the various types of HTML inputs (and select). In fact, there is often a direct equivalent of the ShapeDiver parameter properties with the input attributes. This makes it easy to connect them to web user interfaces. However, ShapeDiver parameters often contain a little more information, which makes it possible to build more complex interfaces.

Parameter definitions

Parameter definitions are javascript objects with a series of properties describing all the relevant attributes of a parameter. One can list all the parameter definitions of a 3D model by calling:

api.parameters.get();

Different parameter types have different set of attributes, depending on their nature and function. However, a few attributes are common to all parameter types.

Common attributes to all parameter types

Those attributes always exist, for all parameters of a model:

• id: The unique identifier for this parameter.
• name: The name of this parameter. It is best practice to choose unique names for the parameters, but it is not mandatory.
• type: The type of the parameter itself. More details in the next section.
• defval: The default value of this parameter, used when the model is initially loaded.
• value: The current value of this parameter in the active session.
• hidden: A boolean describing if the owner of the model decided to hide this parameter from the ShapeDiver control widget.
• order: The position of this parameter defined by the designer in the ShapeDiver control widget.
• note: Additional information about this parameter. There is always a default set of information coming from Grasshopper that will be displayed through tooltips in the online viewer. In the future, designers should have the possibility to override the note with custom information.
• plugin: This string is set by the API when the model is loaded, and indicates which instance of the communication plugin generated it. It will most of the time be CommPlugin_1, except when several models are loaded at the same time.
• visualization: The way this parameter is visualized in Grasshopper and the ShapeDiver control widget. Most types only have one possible visualization, but value lists have several. Read further about this attribute below.

The hidden and order attributes describe the way the designer is showing the parameter on the ShapeDiver platform. They don't contain any inherent information relative to the parameters. However, if you take them into account when building a web application, it's a convenient way from designers to be able to control some aspects of the online interface (hide and show parameters, and control their order).

In the next section, we describe the additional properties that are specific to each parameter type.

Parameter types

Here is a brief description of all the parameter types that can exist in a ShapeDiver model. You can find the always updated list in the API reference. For each type, we describe the specific attributes that describe them further in the parameter definition.

Number types

Four number types are available: Float, Int, Even and Odd. By using the further attributes of those types, they are typically mapped to a range input in a front-end application. Those attributes are:

• min: the minimum value that this parameter can take
• max: the maximum value that this parameter can take
• decimalplaces: (only for Float parameters). The decimal precision of a floating number.

String

The String parameter represents a typical text input. The only additional attribute for Strings is:

• max: the maximum allowed length of the string defined by the designer.

Stringlist

This type is used for lists of values, which are typically represented by dropdown menus using a select element in HTML. This type includes one specific attribute:

• choices: An array of strings representing the various possible values of this parameter.

Note that the strings contained in the choices attribute are the names of the various options in the list, but the actual value of the parameter (stored in the value and defval attributes) is an integer representing an index in the array.

Bool

The boolean type with two possible values: true or false.

Color

Color parameters are described with hexadecimal strings, including opacity (10 digits, e.g. 0xffffffaa).

File

ShapeDiver models can accept several file formats as inputs to be used in the model. They can be sent to the model using javascript files or blobs.

Parameter visualization

All number types have only one possible visualization, called Slider, which corresponds to a range input. On the other hand, Stringlists have four different values, corresponding to the four possible representations of a value list in Grasshopper:
This attribute describes how the UI element controlling a parameter looks in Grasshopper and the ShapeDiver control widget. It merely gives a hint as to how the designer expects it to look in the final web application.

• Dropdown: the typical dropdown menu generated by a select DOM element in HTML.
• Sequence: the UI element representing this parameter in Grasshopper displays only one value at a time with two array on the left and the right for navigating between values. The left arrow disappears when the first value is selected, and the right arrow when the last element is selected.
• Cycle: almost identical to the Sequence visualization style, except the left and right arrow never disappear and let the user cycle through the list of values when reaching the extremities of the array.
• Checklist: a series of checkboxes for the values in the list, allowing to select one or several at the same time.

Of course, these visualization attributes don't contain any inherent information about the parameter. Like the order and hidden attributes, they can be used to give more flexibility to the designer for customizing the final user interface, when they are supported by the web application.