Quickstart Guide

Last Change: 2025-08-27 #dba #jta

Spherene is a cloud-based Grasshopper Add-In service that requires registration. When you activate Spherene computation for the first time, a request window will appear prompting you to enter your API key.

---

Installation & Uninstallation

You can search for Spherene in the Rhino Package Manager to install or uninstall the add-in:

---

Overview of Spherene in Grasshopper

The component tools of Spherene in Grasshopper are organized into two sections: Project and Modifier:

The Project section includes the minimal required components to start a Spherene computation:

• sphe_Project: Provides metadata for the Spherene project
• sphe_Single: Selects the envelope and other inputs for computing a single Spherene surface
• sphe_Solid: Sets input parameters for computing a solid Spherene surface
• sphe_Field: Generates a point map for field attributes such as Density Field, Surface Bias Field, and Thickness Field
• sphe_Compute: Controls the output of the Spherene computation

An example of a basic Spherene computation is provided in Basic computation, illustrating the workflow of components in the Project section. Detailed descriptions of each component are available in the Help window, which you can access by right-clicking on the black header area of the desired component block:

In the Help window, you’ll find the type and description of each input attribute. All attributes marked with a *required* tag are mandatory.

The Modifier section includes components that allow advanced modifications to the Spherene structure (see details in Modifier computation):

• sphe_Boundary: Modifies the Boundaries of the generated Spherene structure
• sphe_Detail: Defines a closed body as a Detail to either add to or subtract from the Spherene geometry
• sphe_Cavity: Introduces a Cavity into the Spherene geometry

---

Examples

The Spherene Add-in generates Adaptive Density Minimal Surfaces (ADMS), also known as Spherene geometry, based on a given envelope. By adjusting various attributes and modifiers, you have the flexibility to tailor the Spherene structure to your specific design needs.

There are five main Spherene attributes and modifiers:

• Field
• Density Field Envelope (Dfenv mesh)
• Boundary
• Detail
• Cavity

In this section, we use a simple example with a cone-shaped envelope to demonstrate how to work with different Spherene attributes and modifiers. The example Grasshopper file can be downloaded here.

We begin with an overview of the general workflow for Spherene computation (see Basic computation). Next, in Field computation and dfenv computation, we show how the Field and Dfenv mesh attributes influence the structure, respectively. Finally, we present examples using the Boundary, Detail, and Cavity modifiers in Modifier computation.

Basic computation

In this example, we compute both a single surface and a solid surface of a Spherene structure using a cone-shaped envelope to demonstrate the general workflow of Spherene computation.
The Grasshopper canvas for this setup is shown below:

The sphe_Compute component accepts four possible inputs:

• Outputs: A text input defining the output type for the computation (0 = Single, 1 = Solid, 2 = Labyrinths, 3 = Halfspaces). For example, we can assign "01" to compute both the single surface and the solid surface.

• Project: Provided by sphe_Project, containing metadata for the current project.

• Single: Provided by sphe_Single, specifying settings for single surface computation.

• Solid: Provided by sphe_Solid, specifying settings for solid surface computation.
  This input can be left empty if only a single surface is requested in the Outputs.

We recommend attaching a Panel to the message output of the sphe_Compute component to monitor computation progress and view any error messages.

The sphe_Project component defines five metadata inputs for the Spherene project:

• Density Reference Thickness (DRT): Specifies the reference wall thickness for the generated Spherene geometry when no Thickness Field is provided—i.e., for constant wall thickness. Lower DRT values result in more complex geometries with higher genus (i.e., more holes or handles) but also increase the computational cost. Halving the DRT can increase computation time by up to 8× and memory usage by up to 6×. The unit of DRT matches the length unit set in your Rhino/Grasshopper model. We recommend using a float value greater than 0.1, for example, 0.4 as a starting value. This input is mandatory.

• Random Seed: Sets the random seed for the computation. Must be an integer between 1 and 999,999,999.

• Max Time: Defines the maximum allowed runtime (minute) before the computation is automatically terminated.

• Naming: Specifies the parent layer name for baking.

• PartName: Specifies the sub-layer name for baking.

The sphe_Single component is used to select the envelope and other input parameters for computing a single Spherene surface:

• env Mesh: Specifies the envelope mesh for the desired part. This input is mandatory, and only one envelope is allowed. It is also possible to use several disjoint, closed meshes merged into one.

• Dfenv Mesh (Density Field Envelope): Defines the envelope used for computing the Spherene geometry (see details in dfenv computation). By default, this is the same as env Mesh.

• Density Field: Defines the percentage ratio between the Spherene volume and the envelope volume: $\text{Density} = \frac{\text{Area of Spherene} \times \text{Thickness}}{\text{Envelope Volume}} \times 100 \%$. This input is mandatory and should come from a sphe_Field component. The density value should be in the range of $[0,100]$.

• Surface Bias Field: Controls how the minimal surface shifts from its neutral position (Surface Bias = 0) along the normal direction. A value of -1 shifts the surface fully in the negative direction; 1 shifts it fully in the positive direction. This input is optional (default = 0) and should also come from sphe_Field . Surface bias affects the surface morphology of the Spherene structure (see Constant field).

• Cavity: Introduces a cavity into the Spherene geometry—useful for integrating inlets, outlets, or other functional features. Should come from a sphe_Cavity component.

• Mesh Reduction: Reduces the polygon count of the output mesh, which can speed up slicing and improve performance in additive manufacturing workflows. Default value is 0% (no reduction).

• Colorize: Colorize the output mesh based on selected quantities.

The sphe_Solid component sets input parameters for computing a solid Spherene surface:

• Thickness Field: Specifies the wall thickness of the generated Spherene geometry. This input should be connected to the output of a sphe_Field component. If not defined, it defaults to the value specified in the Density Reference Thickness (DRT) from sphe_Project . The unit matches the length unit set in your Rhino/Grasshopper model. The thickness value should be in the range of $[0.001,inf)$.

• Boundary: Specifies the boundary conditions to be applied. Should be connected to the output of a sphe_Boundary component.

• Detail: Defines a closed mesh or body to be either added to or subtracted from the Spherene geometry. Connect the output from a sphe_Detail component.

• Mesh Reduction: Reduces the polygon count of the final mesh, which can help speed up slicing for additive manufacturing. Default value is 0% (no reduction).

• Color Scheme: Selects the scheme for color mapping in the visualization.

• Z Factor: Scales the top overhangs of the Spherene geometry slightly to produce thicker top surfaces. This is especially helpful for FFF slicers to generate more solid top layers.

The sphe_Field component is used to generate a point map for various field attributes, including Density Field, Surface Bias Field, and Thickness Field. For examples and usage of different field types, refer to the section Field computation.

Once all settings are configured, start the computation by clicking the compute button on the
sphe_Compute component. After the computation completes, you can visualize the result in Rhino by clicking the bake button on the same component.

Field computation

For each field type:

• If not explicitly set, the default value will be used.
• If only one value is provided, the field is treated as constant across the entire envelope (example see Constant field).
• If multiple values are assigned, a spatial field distribution will be generated over the envelope. For example, assigning two field values to two distinct points creates a gradient between them. You can even assign field values to various geometries to produce more complex field distributions, enabling more advanced and customized designs (example see Field grading).

Constant field

The following example canvas assigns a Surface bias field at a single point, which configures a constant Surface bias field across the envelope:

The following figure shows Spherene geometries generated with various constant Surface Bias:

Field grading

When assigning different field values to multiple vertices, surfaces, bodies, or meshes, a spatial distribution/grading of the field will be generated based on the specified values. In this example, we assign two density field values at two points and give two curved surfaces different Thickness field values:

The example canvas of such setup in Grasshopper is as following:

The resulting Spherene geometry will exhibit a spatially varying thickness and density.

dfenv computation

The dfenv attribute takes a mesh/body as the density field envelope. The default dfenv is set to be the same as the computed envelope env. However, when a dfenv is defined, the Spherene geometry is first generated using dfenv as the envelope, then Boolean trimmed by the original envelope env to produce the final geometry. This enables the generation of Spherene structures at sharp edges or in thin regions where material might otherwise be insufficient, or it can be used to intentionally avoid generating Spherene geometry in specific areas.

In the following example, we aim to generate Spherene structures at the sharp tip and edges of a cone:

To achieve this, we assign a box mesh that is larger than the computed cone envelope env as the density field envelope dfenv:

The canvas of this setup is shown as following:

tip

In rare cases, computations may fail due to mesh Boolean issues (e.g., when dfenv is involved), even though our Boolean algorithm is among the most robust available. These issues can typically be resolved by adjusting the density value or slightly moving or enlarging the dfenv. If the problem persists, we encourage you to contact us directly, and we will assist you with your specific case.

Modifier computation

Boundary modifier

The Boundary modifier allows you to modify the boundaries of the generated Spherene structure. The general logic behind boundary generation is to grow the Spherene structure near the boundary into the boundary surface with a given parameter set, including Hull thickness, Target thickness, Blend distance, and Blend exponent. These parameters control how the geometry blends into the defined boundary region. A schematic of boundary generation is as following:

The Boundary modifier is used to define and control the boundaries of the generated Spherene structure. It allows fine-tuning of surface morphology and blending behavior along selected mesh or surface regions.

• Mesh: Specifies the mesh or surface to be treated as a boundary.

• Front/Back: text that determines which space(s)/labyrinth(s) of the Spherene structure the boundary modification will be applied to. "1" turns on the Front boundary, "0" turns on the Back boundary. For example, entering "01" applies the boundary to both Front and Back labyrinth spaces. The example below illustrates the effect of this setting.

• Hull Thickness: Defines the thickness of the boundary hull region. The unit matches the model’s length unit in Rhino/Grasshopper.

• Target Width: Sets the wall thickness of the solid surface at the boundary location.
  Units match the model’s length unit. When a Boundary is applied to only one side, the resulting solid surface thickness at that boundary will be: $(\text{Target Width} + \text{Thickness})/2$.

• Blend Distance: Controls the distance over which the Spherene structure blends smoothly into the boundary surface. Units match the model’s length unit.

• Blend Exponent: Adjusts the curvature profile of the blend transition.
  Common values:
  0.125 = very tight,
  0.25 = tight,
  0.5 = normal (default),
  1 = straight (45°).

• Hull Naked Edges: Boolean toggle that controls hull generation when the boundary is an open mesh with naked edges and Hull Thickness is not zero. Default = False. When set to True, a hull with sharp edges will be generated along the naked edges of the open mesh boundary. Warning: In rare cases, enabling this option for complex boundary meshes may create unintended cavities.

• Hull Negative Normal: Boolean toggle that restricts blending to the negative normal direction of the selected boundary. Default = True. This option is especially useful when the boundary is located inside the computed envelope, allowing controlled blending between the boundary and the generated Spherene geometry.

tip

In rare cases, Boolean errors may occur when the boundary lies close to the envelope surface. Set Hull Negative Normal = False to allow blending in both directions and produce a thicker hull; this often resolves the issue.

In this example, the cone surface is divided into four sections, with three of them defined as separate boundaries, each using different parameter settings:

The results below compare Spherene geometry without boundaries to those with different boundary configurations:

From the figure above, you can observe the following behavior:

• When Apply on back is ON, the volcano holes on the boundary are filled. When OFF, they remain open.
• When Apply on front is ON, the area surrounding the volcano holes on the boundary is filled. When OFF, it remains open.

Detail modifier

The Detail modifier allows you to define a closed body or mesh as a Detail, which can be added to or subtracted from the Spherene geometry. A Boolean input determines whether the detail is added (False) or subtracted (True).

When adding details, the Detail modifier behaves similarly to the Boundary modifier :
it grows the Spherene structure near the detail geometry into the detail body using a specified parameter set, including Target thickness, Blend distance, and Blend exponent (details refer to [Boundary modifier](#boundary modifier)).

In this example, we add a cylindrical detail (orange) to the bottom of the cone envelope and subtract text bodies (blue) from the cylinder, as shown below:

The corresponding Grasshopper canvas for this setup is shown here:

The figure below illustrates the resulting Spherene geometry after applying these Details:

tip

The text body should protrude slightly from the surface of the subtracting body (in this case, the bottom surface of the cylinder). If it does not, the computation may fail due to Boolean errors, as text bodies often contain complex mesh geometry.

Cavity modifier

The sphe_Cavity modifier allows you to introduce a cavity into the Spherene geometry—particularly useful for integrating inlets, outlets, or other functional features.

In this example, a cylindrical cavity is placed on the front side of the cone envelope. The cavity geometry can be defined as either an open surface or a closed body:

In the Grasshopper canvas, the desired cavity mesh is connected to the sphe_Cavity modifier . The Front/Back Boolean input determines which labyrinth the cavity surface will be applied to.

The following figure compares three cases: a Spherene geometry with Surface Cavity Back labyrinth, Body Cavity Back labyrinth, and Body Cavity Front labyrinth.

From the result, one can see:

• When an open surface is used as the cavity geometry, only the region adjacent to the selected surface becomes void.
• When a closed body is used as the cavity geometry, the entire volume occupied by that body is removed from the Spherene structure.