2.2: Data Retrieval from Models

The Data Model

The data inside a Karamba3D model is organized in a tree-like object structure. The following diagram shows a part of that tree – for full details see “Karamba3D_1_3_3_SDKDoc.chm”:

Retrieving Masses Sorted by Material

The following script (see “DataRetrieval.gh”) shows how to use that model-data to retrieve the mass sorted by material. One can see in fig 2.2.1 the corresponding GH setup. The model comprises two beams made from steel and concrete respectively. The total mass amounts to 87.5 kg, 37.5 kg come from concrete, 50.0 kg from steel.

Figure 2.2.1: Data retrieval from a K3D model.

...
using Karamba.Models;
using Karamba.Utilities;
using Karamba.Materials;
...
private void RunScript(object Model_in)
{
  var model = Model_in as Model;
  if (model == null) {
    throw new ArgumentException("The input is not of type Karamba.Models.Model!");
  }

  var matWeights = new Dictionary<FemMaterial, double>();

  foreach (var elem in model.elems) {
    var mat = elem.crosec.material;
    if (!matWeights.ContainsKey(mat)){
      matWeights[mat] = 0;
    }
    matWeights[mat] += elem.weight(model.nodes);
  }

  var ucf = UnitsConversionFactories.Conv();
  var kg = ucf.weight2kg();

  foreach (var entry in matWeights) {
    Print("Material: " + entry.Key.name + ": " + kg.toBase(entry.Value) + kg.unitB);
  }
}

The first lines contain “using” statements for the name-spaces “Karamba.Utilities” and “Karamba.Materials”. These house the “UnitsConversionFactories”, “INIReader” and “FemMaterial”-classes respectively.

The script starts as before with a type-conversion for the argument “Model_in” from “object” to “Model”. The “matWeights” dictionary provides the mapping from K3D materials to weights. A “foreach”-loop cycles over all elements of the model and gets their materials. If not already present in “matWeights” a new material entry is created. Line 20 updates the material’s total weight.

Handling Physical Units

Creating the output consists of looping over the entries in “matWeights”. The tricky part is to get the physical units right. Internally the C++ part of Karamba3D does not care about physical units. As long as they are consistent the results will be fine. When using SI-units Karamba3D works with these base units: meters (m), kilo Newtons (kN), tons (t) and degrees Celsius. When in Imperial-mode the units of length, force and mass get converted to feet (ft), kilo Pounds force(kipf), kilo Pounds mass (kipm) and degrees Fahrenheit. Units conversion between e.g. centimeter and meter, inch and feet, . . . occurs at output and input only. The material and cross section tables which come with Karamba3D – and can be produced via e.g. the “Generate Cross Section Table”-component – contain values in SI-units only. They get converted to the right units-system (SI or Imperial) on the fly when loading them into Karamba3D.

The matter of mass has it difficulties: in the SI system there is a clear separation between force (kN) and mass (kg) and e.g. Newton’s law takes the form:

$$F[N] = m[kg] * a[m/s^2]$$

since the definition holds:

$$1N = 1kgm/s^2$$

In Imperial units one has Pound-force (lb, sometimes lbf) and Pound-mass (lbm). The former is defined as the force which corresponds to the weight of one pound mass. So “g” – the acceleration of gravity – is not involved. To make Newton’s law work in Imperial units one thus needs to divide the right side by a constant:

$$g_c = 32.174 ft/s^2$$

which is by convention the acceleration of gravity to be used:

$$F [lbf] = m[lbm] · a[ft/s^2]/g_c [ft/s^2]$$

To make calculations involving mass work irrespective of the system of physical units the “kg”- conversion does the following: Under Imperial units masses get scaled by:

$$1/g_c$$

Sometime it happens that one wants to convert weight to mass. In this case weight gets scales by g_user/g_c and g_user for Imperial and SI-units respectively, g_user being the acceleration of gravity given in the karamba.ini-file.

The first step in unit-conversion consists of getting a units-conversion-factory (UCF), (see line 23). This factory converts derived SI or Imperial units (e.g. inch, centimeter, millimeter, . . . ) to base units (e.g. feet, meter). A UCF features a long list of conversion objects, “weight2kg” being one of them. In line 24 a units conversion object gets instantiated using the factory. This lets one convert from force to mass using the acceleration of gravity from the “karamba.ini”-file via the “toBase”-method. Conversion in the other direction works with “toUnit”. The method “unitB” renders a string representation of the unit with brackets.