Anatomy of a Tool

This documentation is for an unreleased (still in testing) version of Cornerstone Tools. Until it is released, its API may experience frequent breaking changes. The current stable release can be found here.


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:

Mode Description
Active Active tools will render and respond to user input. Active tools are able to create new annotations and/or measurements.
Passive Passive tools will render and passively respond to user input. Their data can be manipulated, but not createed.
Enabled Enabled tools will render, but will not respond to input. The "enabled" tool state is essentially a "read-only" state.
Disabled (default) The default state for a tool. Tools that are disabled cannot be interacted with and are not rendered on the enabled element.

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
csTools.setToolModeActive("ToolName", options);
// Passive
csTools.setToolModePassive("ToolName", options);
// Enabled
csTools.setToolModeEnabled("ToolName", options);
// Disabled
csTools.setToolModeDisabled("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
csTools.setToolModeActiveForElement(enabledElement, "ToolName", options);
// Passive
csTools.setToolModePassiveForElement(enabledElement, "ToolName", options);
// Enabled
csTools.setToolModeEnabledForElement(enabledElement, "ToolName", options);
// Disabled
csTools.setToolModeDisabledForElement(enabledElement, "ToolName", options);


  • 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


While changing a tool's mode, you also have the option of updating it's 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 }`
csTools.setToolModeActive("ToolName", { mouseButtonMask: 1 });

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

// A new key is added to the tool's configuration
csTools.setToolModeActive("ToolName", { isTouchActive: false });

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

Common Configuration Options

TODO: Create a property on base tool 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?

Option Mouse Touch Annotation Brush
mouseButtonMask x
preventHandleOutsideImage x
isTouchActive x

Interaction Types

This section needs content


This section needs content

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/disabled, you can give it the enabledOrDisabledBinaryTool:

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

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 a exports a default object containing these functions, e.g.:

// mixins/helloTool.js

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

export default {

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...

Measurement Data

This section needs content

results matching ""

    No results matching ""