Configuration

Tools can contain user-defined parameters, inputs and outputs which are described in the VDescribe method.

The framework uses the description, containing meta-data such as name and type, to populate the tool configuration sections in job files. Any parameter defined is automatically exposed by the GUI and the SDK, and are accessible by tool implementations.

Parameters, inputs and outputs can be added in the following fashion:

GdkFx(kStatus) GdkTestTool_VDescribe(GdkToolInfo toolInfo)
{
   k32s defaultInt = 1;
   k64f defaultFloat = 10.0;

    // ...

    // Tool parameters

    kCheck(GdkToolInfo_AddParam(info, GDK_PARAM_TYPE_INT, "BaseCount", kNULL, &defaultInt, &paramInfo));
    kCheck(GdkToolInfo_AddParam(info, GDK_PARAM_TYPE_FLOAT, "BaseRadius", kNULL, &defaultFloat, &paramInfo));

    // Tool inputs

    kCheck(GdkToolInfo_AddInput(toolInfo, GDK_DATA_TYPE_PROFILE_POINT_CLOUD, "InProfile", kNULL));
    kCheck(GdkToolInfo_AddInput(toolInfo, GDK_DATA_TYPE_GENERIC1, "InGeneric1", &genericInfo));
    kCheck(GdkParamInfo_SetNoneAllowed(genericInfo, kFALSE));

    // Measurement outputs

    kCheck(GdkToolInfo_AddOutput(toolInfo, GDK_DATA_TYPE_MEASUREMENT, "X", "Position X", &measurementInfo));
    params = GdkMeasurementInfo_Params(measurementInfo);
    kCheck(GdkParamsInfo_AddInt(params, "ObjectIndex", kNULL, 0, kNULL));

    // Geometric feature outputs

    kCheck(GdkToolInfo_AddOutput(toolInfo, GDK_DATA_TYPE_FEATURE_CIRCLE, "CircleFeature", "Circle Feature", &featureInfo));

    // Data outputs

    kCheck(GdkToolInfo_AddOutput(toolInfo, GDK_DATA_TYPE_UNIFORM_PROFILE, "DataOutputProfile", "Data Output Profile", &dataOutputInfo));
    kCheck(GdkToolDataOutputInfo_SetHasIntensity(dataOutputInfo, kTRUE));
    kCheck(GdkToolInfo_AddOutput(toolInfo, GDK_DATA_TYPE_GENERIC1, "DataOutputGeneric1", "Data Output Generic1", &dataOutputInfo));

    // ...

    return kOK;
}

Tool parameters are added using the GdkToolInfo_AddParam function. The parameter types can be one of the following:

• GDK_PARAM_TYPE_BOOL
• GDK_PARAM_TYPE_INT
• GDK_PARAM_TYPE_FLOAT
• GDK_PARAM_TYPE_STRING
• GDK_PARAM_TYPE_PROFILE_REGION
• GDK_PARAM_TYPE_SURFACE_REGION
• GDK_PARAM_TYPE_SURFACE_REGION_2D
• GDK_PARAM_TYPE_POINT_SET_REGION

Tool input is added using the GdkToolInfo_AddInput function. An input allows the tool to receive a data stream input of the specified data type. The input stream types can be one of the following:

• GDK_DATA_TYPE_FEATURE_POINT
• GDK_DATA_TYPE_FEATURE_LINE
• GDK_DATA_TYPE_FEATURE_CIRCLE
• GDK_DATA_TYPE_FEATURE_PLANE
• GDK_DATA_TYPE_UNIFORM_PROFILE
• GDK_DATA_TYPE_PROFILE_POINT_CLOUD
• GDK_DATA_TYPE_UNIFORM_SURFACE
• GDK_DATA_TYPE_SURFACE_POINT_CLOUD
• GDK_DATA_TYPE_MESH
• GDK_DATA_TYPE_GENERIC_BASE + n

Tool outputs are specified using the GdkToolInfo_AddOutput function. They allow the tool to generate and send out data in a pre-specified data type format. The output type can be one of the following:

• GDK_DATA_TYPE_MEASUREMENT
• GDK_DATA_TYPE_FEATURE_POINT
• GDK_DATA_TYPE_FEATURE_LINE
• GDK_DATA_TYPE_FEATURE_CIRCLE
• GDK_DATA_TYPE_FEATURE_PLANE
• GDK_DATA_TYPE_UNIFORM_PROFILE
• GDK_DATA_TYPE_PROFILE_POINT_CLOUD
• GDK_DATA_TYPE_UNIFORM_SURFACE
• GDK_DATA_TYPE_SURFACE_POINT_CLOUD
• GDK_DATA_TYPE_MESH
• GDK_DATA_TYPE_GENERIC_BASE + n

When the tool is instantiated by adding a new tool, its configuration can be augmented by the tool's implementation of the GdkTool virtual methods previously mentioned which take as a parameter a handle to an instance of the tool.

With the virtual method implementation, the sensor information (GdkSensorInfo) and tool configuration parameters(GdkToolCfg) that used to be passed into the static methods are derived from the tool handle as illustrated with this example:

GdkFx(kStatus) GdkTestTool_VNewMeasurementConfigInstanced(GdkTestTool tool, GdkMeasurementCfg measurementConfig)
{
    GdkTestToolClass* obj = GdkTestTool_Cast_(tool);
    GdkSensorInfo     sensorInfo;
    GdkToolCfg        config;

    sensorInfo = GdkTool_SensorInfo(tool)
    config = GdkTool_Config(tool);

    ...

    return kOK;
}

When the tool is started (when the user runs the sensor), the parameter values can be either obtained through the GdkTool object through the VStart() method like in the following example or similar code can be used in the VProcess() method when scan data is received.

GdkFx(kStatus) GdkTestTool_VStart(GdkTestTool tool)
{
    GdkTestToolClass* obj = GdkTestTool_Cast_(tool);
    GdkToolCfg config = GdkTool_Config(tool);
    GdkParams params = GdkToolCfg_Parameters(config);
    GdkParam param;

    param = GdkParams_Find(params, "BaseCount");
    GdkLogf("BaseCount: %d", GdkParam_AsInt(param));

    param = GdkParams_Find(params, "BaseRadius");
    GdkLogf("BaseRadius: %f", GdkParam_AsFloat(param));

    obj->measurementIndexX = GdkTool_MeasurementIndexByType(tool, "X");
    obj->featureIndexCircleFeature = GdkTool_FeatureIndexByType(tool, "CircleFeature");
    obj->dataoutputIndexProfile = GdkTool_DataOutputIndexByType(tool, "DataOutputProfile");
    obj->dataoutputIndexGeneric1 = GdkTool_DataOutputIndexByType(tool, "DataOutputGeneric1");

    return kOK;
}

Compatibility

Parameters can be added without affecting backward compatibility if they are marked as optional. By default all parameters are required – if a declared parameter is missing from the configuration (e.g. when loaded from storage), parsing fails. However if the parameter is marked as optional with GdkParamInfo_SetIsOptional, then parsing succeeds even if the parameter is missing from the configuration. In this case the parameter is initialized with the default value, and GdkParam_IsSet returns kFALSE. This provides a simple mechanism for version control.

Versioning

Over the course of the life time of a tool, there may be the need to make changes to its interface e.g. changing or removing parameters. The user-defined aspects of a tool interface, namely its parameters, measurements, and measurement parameters, are captured by GdkToolVersionInfo objects.

By default a tool has just one version (GdkToolInfo_FirstVersion), but more versions may be added using GdkToolInfo_AddVersion. Whenever the interface of a tool has changed, a new version can be registered so that the new interface can be correctly parsed by the framework. When the configuration of a tool instance is saved, the version used at the time is also saved. This saved version is used by the framework to parse the configuration. If a version not defined by the firmware implementation, then that tool instance will not be inactive.

During run-time the user can query the version of the configuration of a tool instance by using GdkToolCfg_Version.

Special Character Restrictions

As a result of optimizations used by the GDK, certain special characters are not to be used as part of any string for naming parameters or type labels within the GDK tool code. Use of these special characters may cause instability and unexpected behaviour with the GDK tool. These are the characters to avoid:

• &
• <
• >
• "
• \r
• \n

Advanced Parameter Handling

While the default parameters should be sufficient for most scenarios, sometimes the tool should be initialized to values that cannot be hardcoded in such a way. In these cases, the GdkTool_VNewToolConfigInstanced, GdkTool_VNewMeasurementConfigInstanced, GdkTool_VNewFeatureConfigInstanced, GdkTool_VNewToolDataOutputConfigInstanced can be overriden to provide more complex initialization logic. These methods are called when new tools and measurements are instantiated by the client, and allows the tool implementation to initialize values using sensor parameters (e.g. active area).

Sometimes it is always necessary to modify the attributes of some parameters based on the value of other parameters. For example regions may need to be hidden when an "Enable Regions" checkbox is unchecked, or the minimum and maximum constraints of a parameter depends on the value of another parameter. For these cases, the GdkTool_VUpdateConfigInstanced method can be overriden to provide dynamic attribute updates. This method is called by the framework whenever the configuration has been updated, to give the tool implementation the opportunity to update the attributes. Note that whenever this method is called, the implementation should update all attributes that should be modified; the framework will not necessarily keep previously set attributes between calls.