Anatomy of a Tool

Modes

A tool's mode (known as tool state in v2) determines how a tool is rendered, and how it can be interacted with. The four standard modes are:

You can quickly test these modes out for yourself by checking out this tool's example/demo page ~TODO~

Changing a Tool's Mode

Assuming you have already enabled one or more elements and added tools to those elements, changing an existing tool's mode can be accomplished one of two ways:

For All Enabled Elements

If you've added a tool with the same name to multiple enabled elements, you can update all instances of the tool by using one of the below methods:

// Active
cornerstoneTools.setToolActive('ToolName', options);
// Passive
cornerstoneTools.setToolPassive('ToolName', options);
// Enabled
cornerstoneTools.setToolEnabled('ToolName', options);
// Disabled
cornerstoneTools.setToolDisabled('ToolName', options);

For a Specific Enabled Element

If you need tool behavior to differ across multiple enabled elements, you can change a tool's mode for a specific enabled element using one of the below methods:

// Active
cornerstoneTools.setToolActiveForElement(
  enabledElement,
  'ToolName',
  {
    mouseButtonMask: 1,
  },
  ['Mouse']
);

// Passive
cornerstoneTools.setToolPassiveForElement(enabledElement, 'ToolName', options);
// Enabled
cornerstoneTools.setToolEnabledForElement(enabledElement, 'ToolName', options);
// Disabled
cornerstoneTools.setToolDisabledForElement(enabledElement, 'ToolName', options);

Caveats

• Some tools may only be able to exist in two of the four modes. For example, the "scale overlay tool" can only be enabled or disabled. Attempts to set it to active will default the tool to enabled.
• Tools of different base types, or inherently complex tools, may bend these guidelines slightly
• 3rd party tools may not adhere to these guidelines

Configuration

While changing a Tool's mode, you also have the option of updating its internal configuration. While Tool configuration varies widely, there are a few commonly used configuration values. For example, all Tools that respond to mouse input use mouseButtonMask to determine which mouse button triggers their behavior. To better understand how configuration is applied, check out the below examples:

// Set's the tool's configuration to `{ mouseButtonMask: 1 }`
cornerstoneTools.setToolActive('ToolName', { mouseButtonMask: 1 });

// Tool's options are left "as-is"
cornerstoneTools.setToolActive('ToolName');
cornerstoneTools.setToolActive('ToolName', null);
cornerstoneTools.setToolActive('ToolName', undefined);
cornerstoneTools.setToolActive('ToolName', {});

// A new key is added to the Tool's configuration
cornerstoneTools.setToolActive('ToolName', { isTouchActive: false });

//  The previous `mouseButtonMask` configuration property's value is updated to `2`
cornerstoneTools.setToolActive('ToolName', { mouseButtonMask: 2 });

Common Configuration Options

TODO: Create a property on BaseTool that is a string list of all configuration options used internally by the tool? Then maintain a list here that denotes what each property is used for?

Interaction Types

This section needs content

Strategies

Tools may optionally have multiple strategies of operation. BaseTool, from which all Tools inherit, takes two arguments related to the Tools strategies:

Upon instantiation of the Tool, the activeStrategy is set to the defaultStrategy. If defaultStrategy is absent, the first function of the strategies is used. The strategies mechanism is entirely optional.

BaseTool has the function applyActiveStrategy (evt, this.configuration) which will execute the activeStrategy, and return any value returned by the strategy.

The strategy can be changed by setting tool.activeStrategy to a new value. The strategy can be reset to the default by calling setDefaultStrategy.

A simple example of a Tool that utilizes the strategy mechanism is the rotate Tool.

Mixins (Behaviours)

Mixins are a set of member functions that can be added to a Tool upon instantiation, giving it additional behavior. Mixins are stored in the top level src/mixins directory.

Adding a mixin to a tool

Mixins can be added to a Tool by passing an array to the mixins argument of its constructor. Each element of the array must be a string containing the name of the mixin you wish to apply.

For example, if a Tool only makes sense to be Enabled or Disabled, you can give it the enabledOrDisabledBinaryTool:

export default class ExampleOverlayTool extends BaseTool {
  // Pass an array of mixins to the constructor.
  constructor(
    name = "ExampleOverlay",
    mixins = ["enabledOrDisabledBinaryTool"]
  ) {
    // Pass mixins to 'super' so that BaseTool's
    // Constructor can attach it to the class.
    super({
      name,
      mixins
    });
  }
}

Thanks to this mixin, the Tool's mode will now switch to Enabled when set Active, and to Disabled when set Passive.

Registering a new mixin

To create a new mixin, create a new file in the mixins directory that contains some functions and exports a default object containing these functions, e.g.:

// mixins/helloTool.js

function helloTool() {
  console.log("Hello Tool!");
}

export default {
  helloTool
};

Then register the mixin in mixins/index.js, which will allow it to be attached to a tool through the mixins argument of its constructor:

// mixins/index.js

// Other imports
import helloTool from "./helloTool.js";

export default {
  // Other registered functions...
  helloTool
};

Measurement Data

This section needs content