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:

• “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.

These files reside in the installation folder of Karamba3D. Their location depends on the chosen installation method:

• Installation via MSI Installer Files are located in Rhino's “Plug-ins” folder. The default path is: C:\Program Files\Rhino 8\Plug-ins\Karamba\

• Installation via Package Manager (YAK) Files are installed in the following folder: C:\Users\<YourUsername>\AppData\Roaming\McNeel\Rhinoceros\packages\8.0\Karamba3D\3.1.40918 (Example shown for version 3.1.40918) To access this folder quickly, use the file explorer and enter %appdata% to navigate to the "Roaming" folder.

Alternatively, the Karamba3D NuGet package can be used to integrate the functionality of karambaCommon (refer to documentation [here]). This method is utilized in the K3D_tests project.

API Documentation and Additional Resources

• API Documentation: The Karamba3D API documentation is available at https://www.karamba3d.com/help/3-1-4.

• Exploring Code: The karambaCommon.dll and karamba.gha files can be inspected using tools like “ILSpy” to decompile and analyze their functionality.

Purpose of Decoupling from Grasshopper

Decoupling Karamba3D (K3D) from Grasshopper was primarily aimed at enabling unit testing for its C# application programming interface (API) to improve code quality.

• Test Project: The Karamba3D test project can be downloaded from https://github.com/karamba3d/K3D_tests. The test cases include code snippets demonstrating API usage, serving as a valuable learning resource for working with the Karamba3D C# API.

Notes on Development and Interface Stability

Karamba3D is under active development, and its interface definitions are subject to change in future releases. Users should account for potential updates when working with the API.