1.1: Scripting with Karamba3D

Sometimes when creating a Grasshopper (GH) definition you may reach a point where it makes sense to switch from GH’s visual computing environment to textual scripting. This is e.g. the case if you want to apply loops, functions or more refined object oriented programming concepts. Other points in favor of a textual approach would be debugging or code reuse.

When installed for Grasshopper Karamba3D consists of three main parts (these files reside in the “Plug-ins”-folder of Rhino - typically C:\ProgramFiles\Rhino6\Plug-ins\Karamba\.):

  • “karamba.dll” is a C++ library which does the numeric calculations.

  • “karambaCommon.dll” provides the .NET user interface to the Karamba3D functionality. It features its own set of geometric types (e.g. vectors, points, meshes,. . . ) and is therefore independent from Grasshopper or Rhino.

  • “karamba.gha” connects GH to “karambaCommon.dll” and takes care of the graphical user- interface.

This scripting guide comes with a help-file (“Karamba3D_1_3_3_SDKDoc.chm” also accessible online Karamba3D 1.3.3 SDK Documentation) which covers “karambaCommon.dll” and parts of “karamba.gha”. It can be found in the “Karamba3D Scripting Examples Github”-collection which accompanies this manual. A useful additional source of information regarding scripting with Karamba3D are the “karambaCommon.dll”- and “karamba.gha” files themselves: Feel free to use a tool like “ILSpy” to decompile them and have a look at their inner workings.

The main incentive behind decoupling K3D from Grasshopper was to enable Unit-testing for the C# application programming interface (API) of Karamba3D and thus enhance its code quality. You can download the Karamba3D test-project from https://github.com/karamba3d/K3D_tests. The test cases represent code-snippets which show how to work with the Karamba3D API and form another useful source of know-how regarding C# of K3D.

Karamba3D is work in progress. So are its interface definitions. Be aware of the fact, that they will probably change in future.