2.1: Hello Karamba3D

For small scripts the Grasshopper scripting components “C# Script”, “VB Script” or “Python Script” from the “Maths” subsection come in handy. A good introduction to scripting in GH can be found in the “Grasshopper Primer”.

All examples which follow can be found in the “Karamba3D Scripting Examples Github”-collection that accompanies this manual. When opening them in Grasshopper do not panic if some components turn red. In that case some paths need adaptation (see below).

In order to get going let’s start with a simple example (see “HelloKaramba3D.gh” in the examples archive): Place a C# scripting component on the canvas, right-click on its icon and select “Manage Assemblies . . . ” from the context menu. In order to make the “karambaCommon.dll” and “karamba.gha” assemblies accessible to your script, click on “Add” left beside “Referenced Assemblies” and browse to the files. They both live in the “Plug-ins”-folder of Rhino (e.g. “C:\ProgramFiles\Rhino6\Plug-ins”). From there all users can access the Karamba3D plug-in. By default one only sees “.dll”-files. Select “Grasshopper Assemblies (*.gha)” from the drop-down list on the lower right side of the browse-window.

The first script (“HelloKaramba3D.gh” in the examples folder) takes a K3D model as input and outputs the number of its nodes and elements. Fig. 2.1.1 displays the Grasshopper definition which generates a Karamba3D-model consisting of one beam only. Zooming in on the C#-components makes small “+” and “-” signs appear next to the input- and output-plugs of the component. Use these to change the number of parameters; right-click on them to change their names. The parameter names which appear on the component act also as the argument names in the underlying C#-script. This sometimes proves to be awkward: input- and output-parameters need to be named differently. Also the fact that input- and output-plugs names normally start with capital letters clashes with customary C# naming conventions where names starting with capital letters normally signify classes.

Fig. 2.1.1: A minimal K3D-model for retrieving the number of elements, materials and cross sections.

The source-code to be added inside the C#-component looks like this:

    ...
    using Karamba.Models;
    ...
    private void RunScript(object Model_in)
    {
        var model = Model_in as Model;    
        if (model == null) {
            throw new ArgumentException("The input is not of type model!");
      }
      Print("Number of Elements: " + model.elems.Count);
      Print("Number of Materials: " + model.materials.Count);
      Print("Number of Cross sections: " + model.crosecs.Count);
    }

The addition of the “using” command in line 2 is for convenience. It spares one to type out the fully qualified names of classes. In case of “Model” in line 6 this would have been “Karamba.Models.Model”. In this example the benefit of the “using” command does not weigh much – longer scripts however gain in readability.

“Model_in” comes as type “object”, so one needs to cast it into its real type to get access to it. The commands in line 6 do so. Since type conversions may fail (think of a user plugging a vector into where the model should go) the “if” in line 7 tests this condition and throws an invalid argument exception if necessary. “model” contains now a reference to the model-object and can be used to retrieve data from it. For a complete specification of the API of the “Model”-class see “Karamba3D_1_3_3_SDKDoc.chm” where it can be found under “Karamba.Models”.