1.2: Basics

Independence from Grasshopper

Karamba3D can operate independently of Grasshopper and Rhino. The API documentation provides an overview of its namespaces:

• Namespaces under Karamba.GHopper These are linked to Grasshopper functionality and are contained within the karamba.gha file. They connect Karamba3D’s C# API to Grasshopper.

• Other Namespaces All remaining namespaces reside within the karambaCommon.dll file and can be utilized without relying on Grasshopper or RhinoCommon.dll. This allows for standalone use of Karamba3D’s core functionalities.

Karamba3D's Geometry Types

The Karamba.Geometry namespace defines the geometry types used in Karamba3D. These types generally mirror Grasshopper's geometry types but without the "D" suffix. For example:

• Grasshopper’s Vector3D corresponds to Karamba3D’s Vector3.

Type Conversion Utilities

• Karamba.GHopper.Utilities.FromGH This static class provides methods for converting Grasshopper-wrapped types (e.g., GH_Vector) to Karamba3D types.

• Karamba.GHopper.Utilities.ToGH This static class provides methods for converting from Karamba3D to Grasshopper-wrapped types.

• Karamba.GHopper.Geometry Namespace This namespace includes the ToKarambaCommon and ToRhino classes. Thes extends Grasshopper and Karamba3D geometry classes with the Convert method. This method enables bi-directional type conversion between Grasshopper and Karamba3D geometry types.

Managing Karamba3D Models: Static Classes and Factories

Most Karamba3D components visible in Grasshopper are backed by static classes within karambaCommon.dll. These static classes perform the core computations. While it is possible to manage Karamba3D models directly using these classes, this approach ties scripts to their specific interface definitions, which may change over time.

Factory-Based Approach for Stability

To provide a more stable API, a factory hierarchy has been implemented under the KarambaCommon.Factories namespace. This approach is recommended for setting up and managing Karamba3D models.

• Access via the Toolkit Class The Toolkit class serves as an entry point to the factory system, offering a more robust and user-friendly method to create and manage Karamba3D models. It also provides sensible default values for many arguments, simplifying setup.

Current and Future Features

• Not all Karamba3D features are currently accessible through the Toolkit.

• The Toolkit will be expanded in future versions and is the preferred method for interacting with Karamba3D.

Learning Resources

For examples of how to use the Toolkit and factory system, refer to the Karamba3D unit-test project: https://github.com/karamba3d/K3D_tests. These test cases demonstrate practical usage of the API and provide valuable insights for developers.