# Tool Registration Arguments

The arguments to `Tool.register` are passed as a Lua table.

Example: Registration of a tool named MyTool

    local _MyTool = Tool.register{
      name="MyTool",
      category="Analysis",
      regions=true,
      hasOverlays=true,
      parameters={
        {name="SomeInteger", type="int"}
      },
      results={
        {name="SomeValue", type="float"},
        {name="Pass", type="bool"}
      },
      thresholds={
        {"SomeValue", type="floatrange", range={0, 1000}, default={10,990}}
      }
    }

These are the outermost settings in the arguments table:

> name (`string`)

>   The name of the tool.
>   Default: The name of the app

>   This is an identifier, and should not contain spaces. The name displayed in the UI should be specified in Language resource files. The exact value of `name` is used if no translation is available.

> category (`string`) required

>   The tool category, must be `"Analysis"`.

> subcategory (`string`)

>   The tool subcategory. Determines in which category the tool appears in the tool menu. Allowed values are `"Classify"`, `"CountAndFind"`, `"Locate"`, `"Measure"`, `"Read"`, `"Shape"`, `"Verify"`, and `"Other"`.
>   Default: `"Other"`

> dimension (`string`)

>   Can be `"2D"` or `"3D"`. This only affects which section in the tool menu the tool appears in for products that include both 2D and 3D tools. Set to `"3D"` if the tool uses the Height component (see `input:getProviderData` and `Nova.Types.DataComponent`) or if the tool performs a calculation in 3D space.

> regions (`boolean` or `regions definition`)

>   Defines if the tool supports regions, and if so which types. Setting this to `true` will allow an unlimited number of 2D regions of any shapes. When `true`, or with a `regions definition` that is not limited to one region of a fixed type, the tool will have a UI control for specifying regions to operate on.
>   Default: `false`

> hasOverlays (`boolean`)

>   When `true`, the tool can produce visualization overlays in the Nova viewer.
>   Default: `false`

>   Note

>   When using `regions=true`, it is usually best to set `hasOverlays` to true.

> maxInstances (`int`)

>   The maximum number of simultaneous instances the tool allows. When not specified, the number of instances is unrestricted.
>   Default: unlimited

> supportChildTools (`boolean`)

>   When `true`, tools can be inserted under this tool, and will be executed after. See Child tool functionality.
>   Default: `false`

> requiresTeach (`boolean`)

>   This argument is used when a tool should have a teach process. When `true`, the tool requires a reference image. A teach panel is automatically displayed when a tool requires teach. It will only be possible to edit regions when Nova is in reference image view.
>   Default: `false`

> parameters (`parameter list`)

>   A list of parameter definitions which define the set of configurable parameters for instances of a tool.
>   Default: none

> results (`result list`)

>   A list of result definitions which define the set of result types the tool provides.
>   Default: none

> thresholds (`threshold list`)

>   A `list` of threshold definitions which define the configurable pass/fail thresholds for the defined results.
>   Default: none

## Regions definition

The supported regions for a tool can be defined by a table entry in `Tool.register`. The table can include the following settings:

> is3D (`boolean`)

>   When `true` the tool will have 3D regions with a configurable height range.

> maxNumber (`int`)

>   The maximum number of regions for the tool. Setting this to 1 means that the tool only supports one positive region.

> shapes (`table`)

>   A list of one or more allowed region shapes.

>   The supported shapes for 2D tool regions are “RECTANGLE”, “ELLIPSE” and “POLYLINE”. For 3D tool regions only “RECTANGLE” and “ELLIPSE” are supported.

The example below shows the definition for a tool that can only have one 2D region with a rectangle or ellipse shape:

    regions={is3D=false, maxNumber=1, shapes={"RECTANGLE", "ELLIPSE"}},

## Parameter list

The `parameters` entry of the tool registration arguments is a list of `parameter definitions`. These define the user-configurable parameters of a tool.

    parameters={
      {<parameter definition 1>},
      {<parameter definition 2>},
      {...}}
    },

## Parameter definition

    parameters={
      {name="SomeInteger", type="int"}
    }

A parameter is defined by a parameter definition table entry in the `parameter` list for `Tool.register`. The parameter values for these parameters are made available to tool instances via the `parameters` interface.

For the different types of parameters, see Parameter types.

General parameter definition fields

These fields can be used for most parameter types.

> name (`string`) required

>   Specifies the name of the parameter.

>   This is an identifier, and should not contain spaces. The name displayed in the UI should be specified in Language resource files. The exact value of `name` is used if no translation is available.

> type (`string`) required

>   Specifies the parameter type, see Parameter types.

> default (type specific) type specific

>   Specifies the default value. The data-type depends on the `type` entry for the parameter, see Parameter types for specifics.

> range (type specific) type specific

>   Specifies the possible range of values. The data-type depends on the `type` entry for the parameter, see Parameter types for specifics.

> ui (`boolean|table`) type specific

>   Allows customizing the parameter appearance in the tool panel in the user interface.

>   When set to a boolean, this controls if the parameter is visible in the UI. With `ui=false` there will be no control for the parameter in the user interface.

>   When specified as a table, `ui={...}` some aspects of the UI representation can be controlled. The options are `type`-specific, see the documentation for the individual parameter types

> affectsTeach (`boolean`)

>   When a tool requires teach, see `requiresTeach` in Tool Registration Arguments, it might be necessary for the tool to reteach after a parameter has been changed. In that case this property should be used to indicate that. If the reference image is removed, a parameter with this property set will be disabled since reteach is no longer possible.

> optional (`table`)

>   When present, the parameter will be optional and can be enabled or disabled in the user interface. This value should be a table with a `default`-entry that specifies whether the optional parameter will be disabled (for `default=false`) or enabled (for `default=true`) initially. See Optional parameters for details.

## Optional parameters

Optional parameters can be disabled with a checkbox in the user interface, and should, when disabled, not affect the tool.

A parameter is specified to be optional with the `optional` field:

>         {name="MyOptional", optional={default=false}, type="intrange", range={0, 20}}

The `default` parameter to `optional` decides if the parameter is enabled by default (true) or disabled (false) when the tool is first created.

For optional parameters, “.value” must be specified explicitly to access the value:

>       local myOptional = self.parameters.MyOptional.value

The enable-state is accessed with “.enabled”:

>       local optionalEnabled = self.parameters.MyOptional.enabled

## Result list

The `results` entry of the tool registration arguments is a list of `result definitions`. These define the results that a tool produces when executed.

    results={
      {<result definition 1>},
      {<result definition 2>},
      {...},
    }

## Result definition

    results={
      {name="SomeValue", type="int"}
    }

A tool result is defined by a result definition table entry in the `results` list for `Tool.register`.

For the different types of results, see Result types.

Tools set the values for their defined results for an execution in their `execute` method using the `output:add` method.

A result definition can have a corresponding threshold definition that defines a customizable interval for determining the pass/fail-status of a result.

General result fields

These fields can be used for most result types.

> name(`string`) required

>   Specifies the name of the result. If the result has a threshold, the threshold name should be the same as the result name.

> type(`string`) required

>   Specifies the result type, see Result types.

## Threshold list

The `thresholds` entry of the tool registration arguments is a list of `threshold definitions`. These should correspond to items in the result list, and define customizable ranges for determining the pass/fail result of the tool.

    thresholds={
      {<threshold definition 1>},
      {<threshold definition 2>},
      {...},
    }

## Threshold definition

    thresholds={
      {name="SomeValue", type="intrange", range={0, 1000}, default={10, 990}}
    }

A threshold is defined by a threshold definition table entry in the threshold list entry to `Tool.register`. The name of a threshold should be the same as the name of a result definition.

A threshold definition defines a customizable interval that allows a user to specify the acceptable values of a result, within boundaries specified by the threshold.

Tools access the user-configured threshold values via `self.thresholds` in their `execute` method.

For the different types of thresholds, see Threshold types.

General threshold fields

These fields can be used for all thresholds. For the additional required fields that are `type`-dependent see Threshold types.

> name(`string`) required

>   Specifies the name of the threshold. The name should be the same as the name of the result this threshold applies to.

> type(`string`) required

>   Specifies the threshold type, see Threshold types.