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.

What is CornerstoneTools.js

Cornerstone Tools is a javascript library that assist in annotating, segmenting, and measuring medical images. This library also provides a framework for creating new tools, managing all tools in a consistent cohesive manner, and importing/exporting tool measurement data.

This library is not stand-alone. It builds on top of Cornerstone; a standards compliant, fast, and extensible JavaScript library that displays interactive medical images.

Getting Started

The easiest way to try out Cornerstone Tools is using the JSFiddle Hello World example. Feel free to open it in another tab and follow along as we go through some basic examples. Or, you can create an index.html file and include Cornerstone Tools with:

<!-- Dependencies -->
<script src="[email protected]"></script>
<script src="[email protected]/dist/cornerstoneMath.js"></script>
<script src="[email protected]/dist/cornerstone.js"></script>
<script src="[email protected]/dist/cornerstoneWebImageLoader.js"></script>

<!-- development version, includes helpful console warnings -->
<script src="[email protected]/dist/cornerstoneTools.js"></script>


<!-- Dependencies -->
<script src="[email protected]"></script>
<script src="[email protected]"></script>
<script src="[email protected]"></script>
<script src="[email protected]"></script>

<!-- production version, optimized for size and speed -->
<script src="[email protected]"></script>

The Installation page provides more options for installing Cornerstone Tools.


If you find the dependencies confusing, here is a high level overview of why each is included and necessary for Cornerstone Tools to function:

Dependency Purpose Alternatives
Hammer.js Adds cross-browser support for touch events and gestures N/A
Cornerstone Math Is a dependency some tools use to aid in vector math, or other complex operations N/A
Cornerstone (Core) Renders our image, and provides useful events and methods to make tools that respond to viewport changes possible N/A
Cornerstone Web Image Loader Adds the ability to "fetch" PNG / JPEG images from http or https URLs. Other image loaders exist to load NIFTI or DICOM images into Cornerstone CornerstoneWADOImageLoader (DICOM) / CornerstoneNIFTIImageLoader (NIFTI)

If you find this overly complicated and have alternative solutions to managing and using dependencies, we are always looking for new ideas on how to simplify the process. Please do not hesitate to create a GitHub issue and discuss (:


Previous versions of Cornerstone Tools required a strong knowledge of its internals to enable/disable different features and functionality. Now, sensible defaults are applied when you initialize a new instance of Cornerstone Tools. You also have the ability to override those defaults, for example:

To disable touch event listeners:

const config = {
  touchEnabled: false
const csTools = cornerstoneTools.init(config);

A full list of the settings and their default can be found here: globalConfigurationModule.js

Adding and Using Tools

In previous versions of Cornerstone Tools, users would need to implement their own tool manager. This version includes the concept of "adding" tools to enabled elements to make tracking and managing tool state across your application easier.

Adding a tool to one or more enabled elements:

In this example, we're adding a built in tool to an enabledElement.

const csTools = cornerstoneTools.init();
const LengthTool = cornerstoneTools.LengthTool;

// Make sure we have at least one element enabled
const element = document.querySelector("#element-1");

// Adds tool to ALL currently enabledElements

// OR add the tool to a specific enabledElement
csTools.addToolForElement(element, LengthTool);

Activating an added tool:

When a tool is added, it's default mode is "disabled". When a tool's mode is "active", it can be used; if it has measurement data, that data can be created or interacted with. You can read more about changing a tool's mode in the anatomy of a tool section of our docs. In this example, we change an added tool's mode to "active":

// Activate the tool for ALL currently enabledElements
csTools.setToolActive(, { mouseButtonMask: 1 });

// OR activate the tool for a specific enabledElement
csTools.setToolActiveForElement(enabledElement,, {
  mouseButtonMask: 1

Now that our tool is active, we should be able to use our LengthTool to draw length annotations on the enabled element. Having trouble or just want to see a quick demo? Check out this jsfiddle!

Next Steps

This section needs content

results matching ""

    No results matching ""