Simple Data Types

This guide discusses how Grasshopper deals with data items and types.

Overview

It’s a rather complicated topic as data is an integral part of the Grasshopper process and GUI. Grasshopper needs to be able to (de)serialize data, display data in tooltips, convert data to other types of data, prompt the user for persistent data, draw geometry preview data in viewports and bake geometric data. In this topic I’ll only talk about non-geometric data, we’ll get to previews and baking in a later topic.

Practically all native data types in Grasshopper are based either on a .NET Framework type or a RhinoCommon type. For example System.Boolean, System.String, Rhino.Geometry.Point3d and Rhino.Geometry.Brep to name but a few. However, the parameters in Grasshopper don’t directly store Booleans, String, Points and Breps as these types can’t handle themselves in the cauldron that is Grasshopper.

Prerequisites

We will not be dealing with any of the basics of component development in this guide. Please start with the Your First Component guide and the Simple Component guide before starting this one.

Before you start, create a new class that derives from Grasshopper.Kernel.GH_Component, as outlined in the Simple Component guide.

The IGH_Goo interface

In this section I’ll briefly discuss all the methods and properties that are defined in IGH_Goo. What they’re for, who uses them at what time, etc, etc.

All data used in Grasshopper must implement the IGH_Goo interface. IGH_Goo defines the bare minimum of methods and properties for any kind of data before it is allowed to play ball.

IsValid

bool IsValid { get{} }
ReadOnly Property IsValid() As Boolean

Not all data types are valid all the time, and this property allows you to test the current instance of your data. When data is invalid it will often be ignored by components.

TypeName

string TypeName { get{} }
ReadOnly Property TypeName() As String

This property must return a human-readable name for your data type.

TypeDescription

string TypeDescription { get{} }
ReadOnly Property TypeDescription() As String

This property must return a human-readable description of your data type.

Duplicate

IGH_Goo Duplicate()
Function Duplicate() As IGH_Goo

This function must return an exact duplicate of the data item. Data is typically shared amongst multiple Grasshopper parameters, so before data is changed, it first needs to copy itself. When data only contains ValueTypes and Primitives, making a copy of an instance is usually quite easy.

ToString

string ToString()
Function ToString() As String

This function is called whenever Grasshopper needs a human-readable version of your data. It is this function that populates the data panel in parameter tooltips. You don’t need to create a String that is parsable, it only needs to be somewhat informative.

EmitProxy

IGH_GooProxy EmitProxy()
Function EmitProxy() As IGH_GooProxy

Data proxies are used in the Data Collection Manager. You can ignore this function (i.e. Return Nothing) without crippling your data type.

CastTo

bool CastTo<T>(out T target)
Function CastTo(Of T)(ByRef target As T) As Boolean

Data Casting is a core feature of Grasshopper data. It basically allows data types defined in Grasshopper add-ons to become an integral part of Grasshopper. Lets assume that we have a Component that operates on data type [A]. But instead of playing nice, we provide data of type [B]. Two conversion (casting) attempts will be made in order to change [B] into [A]. If [B] implements IGH_Goo, then it is asked if it knows how to convert itself into an instance of [A]. Failing that, if [A] implements IGH_Goo, it is asked whether or not it knows how to construct itself from an instance of [B].

The CastTo() function is responsible for step 1. The CastTo() method is a generic method, meaning the types on which it operates are not defined until the method is actually called. This allows the function to operate “intelligently” on data types. It also unfortunately means you have to be “intelligent” when implementing this function.

See the Grasshopper Data Types guide for more information on conversion.

CastFrom

bool CastFrom(object source)
Function CastFrom(ByVal source As Object) As Boolean

The CastFrom() function is responsible for step 2 of data casting. Some kind of data is provided as a source object and if the local Type knows how to “read” the source data it can perform the conversion.

See the Grasshopper Data Types guide for more information on conversion.

ScriptVariable

object ScriptVariable()
Function ScriptVariable() As Object

When data is fed into a VB or C# script component, it is usually stripped of IGH_Goo specific data and methods. The ScriptVariable() method allows a data type to provide a stripped down version of itself for use in a Script component.

The GH_Goo abstract class

Although all data in Grasshopper must implement the IGH_Goo interface, it is not necessary to actually write a type from scratch. It is good practice to inherit from the abstract class GH_Goo<T>, as it takes care of some of the basic functionality. GH_Goo is a generic type (that’s what the “<T>” bit means), where T is the actual type you’re wrapping. GH_Goo<T> has several abstract methods and properties which must be implemented, but a lot of the other methods are already implemented with basic (though usually useless) functionality.

An Example Type

We’ll now create a very simple custom type. This will introduce the basic concept of custom type development, without dealing with any of the baking and previewing logic yet. Our custom type will be a TriState flag, similar to boolean values but with an extra state called “Unknown”. We’ll represent these different states using integers:

  • Negative One -1 = Unknown
  • Zero 0 = False
  • One 1 = True

We’ll start with the general class layout, then drill down into each individual function. Create a new public class called TriStateType and inherit from GH_Goo<Integer>. Be sure to import the Grasshopper Kernel and Kernel.Types namespaces as we’ll need them both:

using Grasshopper.Kernel;
using Grasshopper.Kernel.Types;

namespace MyTypes
{
  public class TriStateType : GH_Goo<int>
  {

  }
}
Imports Grasshopper.Kernel
Imports Grasshopper.Kernel.Types

Namespace MyTypes
  Public Class TriStateType
    Inherits GH_Goo(Of Integer)

  End Class
End Namespace

Constructors

Unless a constructor is defined, .NET classes always have a default constructor which initializes all the fields of the class to their default values. This constructor does not require any inputs and when you develop custom types it is a good idea to always provide a default constructor. If there is no default constructor, then class instances cannot be created automatically which thwarts certain algorithms in Grasshopper.

In addition to a default constructor I also find it useful to supply so called copy constructors which create a new instance of the type class with a preset value.

// Default Constructor, sets the state to Unknown.
public TriStateType()
{
  this.Value = -1;
}

// Constructor with initial value
public TriStateType(int tristateValue)
{
  this.Value = tristateValue;
}

// Copy Constructor
public TriStateType(TriStateType tristateSource)
{
  this.Value = tristateSource.Value;
}

// Duplication method (technically not a constructor)
public override IGH_Goo Duplicate()
{
  return new TriStateType(this);
}
'' Default Constructor, sets the state to Unknown.
Public Sub New()
  Me.Value = -1
End Sub

'' Constructor with initial value
Public Sub New(ByVal tristateValue As Integer)
  Me.Value = tristateValue
End Sub

'' Copy Constructor
Public Sub New(ByVal tristateSource As TriStateType)
  Value = tristateSource.Value
End Sub

'' Duplication method (technically not a constructor)
Public Overrides Function Duplicate() As Kernel.Types.IGH_Goo
  Return New TriStateType(Me)
End Function

Incidentally, the Value property which we are using to assign integers to our local instance is provided by the GH_Goo<T> base class. GH_Goo<T> defines a protected field of type T called m_value and also a public accessor property called Value which gets or sets the m_value field.

In this particular case, it actually makes sense to override the default Value property implementation, as the number of sensible values we can assign (-1, 0 and +1) is a subset of the total number values available through the Integer data type. It makes no sense to assign -62 for example. We could of course agree that all negative values indicate an “Unknown” state, but we should try to restrict ourselves to only three integer values:

// Override the Value property to strip non-sensical states.
public override int Value
{
  get { return base.Value; }
  set
  {
    if (value < -1) { value = -1; }
    if (value > +1) { value = +1; }
    base.Value = value;
  }
}
'' Override the Value property to strip non-sensical states.
Public Overrides Property Value() As Integer
  Get
    Return MyBase.Value
  End Get
  Set(ByVal value As Integer)
    If (value < -1) Then value = -1
    If (value > +1) Then value = +1
    MyBase.Value = value
  End Set
End Property

Formatters

Formatting data is primarily a User Interface task. Both the data type and the data state need to be presented in human-readable form every now and again. This mostly involves readonly properties as looking at data does not change its state:

// TriState instances are always valid
public override bool IsValid
{
  get { return true; }
}

// Return a string with the name of this Type.
public override string TypeName
{
  get { return "TriState"; }
}

// Return a string describing what this Type is about.
public override string TypeDescription
{
  get { return "A TriState Value (True, False or Unknown)"; }
}

// Return a string representation of the state (value) of this instance.
public override string ToString()
{
  if (this.Value == 0) { return "False"; }
  if (this.Value > 0) { return "True"; }
  return "Unknown";
}
'' TriState instances are always valid
Public Overrides ReadOnly Property IsValid() As Boolean
  Get
    Return True
  End Get
End Property

'' Return a string with the name of this Type.
Public Overrides ReadOnly Property TypeName() As String
  Get
    Return "TriState"
  End Get
End Property

'' Return a string describing what this Type is about.
Public Overrides ReadOnly Property TypeDescription() As String
  Get
    Return "A TriState Value (True, False or Unknown)"
  End Get
End Property

'' Return a string representation of the state (value) of this instance.
Public Overrides Function ToString() As String
  If (Value = 0) Then Return "False"
  If (Value > 0) Then Return "True"
  Return "Unknown"
End Function

Serialization

Some data types can be stored as persistent data. Persistent data must be able to serialize and deserialize itself from a Grasshopper file. Most simple types support this feature (Booleans, Integers, Strings, Colours, Circles, Planes etc.), most complex geometry types cannot be stored as persistent data (Curves, Breps, Meshes). If possible, you should aim to provide robust (de)serialization for your data:

// Serialize this instance to a Grasshopper writer object.
public override bool Write(GH_IO.Serialization.GH_IWriter writer)
{
  writer.SetInt32("tri", this.Value);
  return true;
}

// Deserialize this instance from a Grasshopper reader object.
public override bool Read(GH_IO.Serialization.GH_IReader reader)
{
  this.Value = reader.GetInt32("tri");
  return true;
}
'' Serialize this instance to a Grasshopper writer object.
Public Overrides Function Write(ByVal writer As GH_IO.Serialization.GH_IWriter) As Boolean
  writer.SetInt32("tri", Value)
  Return True
End Function

'' Deserialize this instance from a Grasshopper reader object.
Public Overrides Function Read(ByVal reader As GH_IO.Serialization.GH_IReader) As Boolean
  Value = reader.GetInt32("tri")
  Return True
End Function

Casting

There are three casting methods on IGH_Goo; the CastFrom() and CastTo() methods that facilitate conversions between different types of data and the ScriptVariable() method which creates a safe instance of this data to be used inside untrusted code (such as VB or C# Script components).

// Return the Integer we use to represent the TriState flag.
public override object ScriptVariable()
{
  return this.Value;
}

// This function is called when Grasshopper needs to convert this
// instance of TriStateType into some other type Q.
public override bool CastTo<Q>(ref Q target)
{
  //First, see if Q is similar to the Integer primitive.
  if (typeof(Q).IsAssignableFrom(typeof(int)))
  {
    object ptr = this.Value;
    target = (Q)ptr;
    return true;
  }

  //Then, see if Q is similar to the GH_Integer type.
  if (typeof(Q).IsAssignableFrom(typeof(GH_Integer)))
  {
    object ptr = new GH_Integer(this.Value);
    target = (Q)ptr;
    return true;
  }

  //We could choose to also handle casts to Boolean, GH_Boolean,
  //Double and GH_Number, but this is left as an exercise for the reader.
  return false;
}

// This function is called when Grasshopper needs to convert other data
// into TriStateType.
public override bool CastFrom(object source)
{
  //Abort immediately on bogus data.
  if (source == null) { return false; }

  //Use the Grasshopper Integer converter. By specifying GH_Conversion.Both
  //we will get both exact and fuzzy results. You should always try to use the
  //methods available through GH_Convert as they are extensive and consistent.
  int val;
  if (GH_Convert.ToInt32(source, out val, GH_Conversion.Both))
  {
    this.Value = val;
    return true;
  }

  //If the integer conversion failed, we can still try to parse Strings.
  //If possible, you should ensure that your data type can 'deserialize' itself
  //from the output of the ToString() method.
  string str = null;
  if (GH_Convert.ToString(source, out str, GH_Conversion.Both))
  {
    switch (str.ToUpperInvariant())
    {
      case "FALSE":
      case "F":
      case "NO":
      case "N":
        this.Value = 0;
        return true;

      case "TRUE":
      case "T":
      case "YES":
      case "Y":
        this.Value = +1;
        return true;

      case "UNKNOWN":
      case "UNSET":
      case "MAYBE":
      case "DUNNO":
      case "?":
        this.Value = -1;
        return true;
    }
  }

  //We've exhausted the possible conversions, it seems that source
  //cannot be converted into a TriStateType after all.
  return false;
}
'' Return the Integer we use to represent the TriState flag.
Public Overrides Function ScriptVariable() As Object
  Return Value
End Function

'' This function is called when Grasshopper needs to convert this
'' instance of TriStateType into some other type Q.
Public Overrides Function CastTo(Of Q)(ByRef target As Q) As Boolean
  'First, see if Q is similar to the Integer primitive.
  If (GetType(Q).IsAssignableFrom(GetType(Integer))) Then
    Dim ptr As Object = Value
    target = DirectCast(ptr, Q)
    Return True
  End If

  'Then, see if Q is similar to the GH_Integer type.
  If (GetType(Q).IsAssignableFrom(GetType(GH_Integer))) Then
    Dim int As Object = New GH_Integer(Value)
    target = DirectCast(int, Q)
    Return True
  End If

  'We could choose to also handle casts to Boolean, GH_Boolean,
  'Double and GH_Number, but this is left as an exercise for the reader.
  Return False
End Function

'' This function is called when Grasshopper needs to convert other data
'' into TriStateType.
Public Overrides Function CastFrom(ByVal source As Object) As Boolean
  'Abort immediately on bogus data.
  If (source Is Nothing) Then Return False

  'Use the Grasshopper Integer converter. By specifying GH_Conversion.Both
  'we will get both exact and fuzzy results. You should always try to use the
  'methods available through GH_Convert as they are extensive and consistent.
  Dim int As Integer
  If (GH_Convert.ToInt32(source, int, GH_Conversion.Both)) Then
    Value = int
    Return True
  End If

  'If the integer conversion failed, we can still try to parse Strings.
  'If possible, you should ensure that your data type can 'deserialize' itself
  'from the output of the ToString() method.
  Dim str As String = Nothing
  If (GH_Convert.ToString(source, str, GH_Conversion.Both)) Then
    Select Case str.ToUpperInvariant()
      Case "FALSE", "F", "NO", "N"
        Value = 0
        Return True
      Case "TRUE", "T", "YES", "Y"
        Value = +1
        Return True
      Case "UNKNOWN", "UNSET", "MAYBE", "DUNNO", "?"
        Value = -1
        Return True
    End Select
  End If

  'We've exhausted the possible conversions, it seems that source
  'cannot be converted into a TriStateType after all.
  Return False
End Function