cornerstone-tools is the deprecated plugin layer for the Cornerstone.js medical imaging library

A plugin layer for medical imaging, now pointing elsewhere

cornerstone-tools is a simple, extensible framework for creating tools on top of Cornerstone.js, and it includes common tool implementations while leveraging DICOM metadata, when available, for advanced functionality. It is a JavaScript project under the MIT licence, with the package name cornerstone-tools and the description medical imaging tools for the Cornerstone library.

The first thing to know, though, is that the project is done. The repository description is literally marked as deprecated with a pointer to Cornerstone3D, and the README opens with a notice that Cornerstone.js has evolved, that Cornerstone3D is being introduced, and that users should navigate to the new repository for the latest updates and improvements.

That is not a plan to finish the library, it is a hand-off. The last tagged release listed is v6.0.10 from 2023-07-21, before that v6.0.9 from 2023-03-27 and v6.0.8 from 2022-08-10, and the last push to the repository was on 2026-06-25.

So the correct way to read this project today is in two registers. For a team that already runs a Cornerstone.js viewer, it is a maintained dependency they need to understand and possibly patch, and the source and documentation are the reference. For a team starting something new in medical imaging, the useful content here is the design, and the answer to the question of which library to use is in the successor project.

The documentation lives at tools.cornerstonejs.org, with the examples, the API reference and a book, and the repository still carries the full source under src, the docs directory, the examples directory and a config directory with the webpack setup.

The problem: tools that stop behaving the same way

The README's framing of the problem is short and specific, and it explains why a framework exists at all when the underlying library already works.

Building one or two tools on top of Cornerstone.js is not that difficult. The difficulty arrives as the number of tools grows, and the list of problems that appear is specific enough to be recognisable to anyone who has built a medical imaging viewer.

Tools should behave and be configurable in a consistent way. You have to manage tools across multiple cornerstone enabled elements, which is the part that bites in a viewer with a viewport and a thumbnail stack, or a side-by-side comparison layout. There are tools that need knowledge of a fellow tool's state, for instance a measurement tool that has to know what the annotation tool currently has selected. And you need the ability to drop in other people's tools and have them just work.

The stated solution is a highly pluggable and extensible approach, and the characteristics are chosen deliberately. It is a light-weight solution whose only dependencies are libraries within the Cornerstone family, and instead of trying to do everything it aims to be extensible and pluggable to aid in the rapid development of new tools. The ambition stated in the README is that tools created using cornerstone-tools can be easily shared, allowing for the creation of a broader ecosystem.

That last goal is the one the project actually delivered on. The README documents third-party tool plugins, an image statistics tool and a rotated elliptical ROI tool, each with a source and a demo link, and thanks are given to the tool authors for sharing their work. The core annotation tools it ships are Angle, Elliptical ROI, Length and Rectangle ROI.

BaseTool and the configuration contract

The mechanism underneath the framework is a base class, and the example in the README shows the whole shape of a tool in one class.

import cornerstone from 'cornerstone-core';
import { BaseTool } from 'cornerstone-tools';
import basicLevelingStrategy from '...';

export default class WwwcTool extends BaseTool {
  constructor(configuration = {}) {
    const defaultConfig = {
      name: 'Wwwc',
      strategies: { basicLevelingStrategy },
      supportedInteractionTypes: ['Mouse', 'Touch'],
      configuration: {
        orientation: 0,
      },
    };
    const initialConfiguration = Object.assign(defaultConfig, configuration);

    super(initialConfiguration);
  }

  mouseDragCallback(evt) {
    this.applyActiveStrategy(evt);

    cornerstone.setViewport(evt.detail.element, evt.detail.viewport);
  }

  touchDragCallback(evt) {
    evt.stopImmediatePropagation();
    this.applyActiveStrategy(evt);

    cornerstone.setViewport(evt.detail.element, evt.detail.viewport);
  }
}

The contract has four visible parts. The tool names itself, so the framework can find and configure it. It declares a set of strategies, which is how the interaction behaviour is separated from the rendering. It declares the supported interaction types, here Mouse and Touch, which is what lets a tool behave consistently when a viewer supports both input methods. And it carries a configuration object, merged with the caller's configuration through Object.assign over the defaults.

The interaction hooks are named for the input device, mouseDragCallback and touchDragCallback, and the mouse hook applies the active strategy and pushes the resulting viewport back into cornerstone with setViewport, while touchDragCallback additionally stops the touch event propagating further before doing the same.

That last call is the part that ties the tool to the shared viewport state, and it is why the enabled element and viewport handling in the base class matter as much as the individual tools.

Peer dependencies are the real installation hurdle

The installation section is short, and the README is unusually direct about where the difficulty lies.

The module is distributed via npm, bundled with node, and should be installed as one of your project's dependencies. The two commands given are for the newest version and for the legacy 2.4.x branch:

// To install the newest version
npm install --save cornerstone-tools

// To install the legacy version (2.4.x branch)
npm install --save cornerstone-tools@2

What makes this more than a one-line install is the peer dependencies. The library lists peerDependencies for hammerjs, described as providing better touch support, for cornerstone-core, for cornerstone-math, which is said to simplify and provide shared complex tool math logic, and for any Cornerstone image loader. Two are named: cornerstone-web-image-loader for JPEG and PNG images, and cornerstone-wado-image-loader for DICOM images, which also parses tags for tool use.

That last detail is worth underlining, because it explains the DICOM metadata claim in the project description. The tools get their advanced functionality from tags the WADO loader has already parsed, which is why the image loader is a peer dependency rather than an optional extra.

The README also warns that setting up and configuring the dependencies of cornerstone-tools can be the biggest hurdle to getting started, and points to the installation documentation. The browser support target is recorded in a browserslist configuration that includes IE 11, with a note that if you need to support the IE11 browser you will need to provide polyfills as needed.

The package manifest itself asks for node >=8.16.0, and the build is a webpack production and development bundle with a Babel configuration, ESLint, Prettier, Jest for unit tests and docma for the API documentation.

Where cornerstone-tools is the wrong thing to reach for

Three limits, and the first one is the deprecation itself.

The first is that this is the previous generation. Cornerstone3D is the successor the project points at, with advanced rendering, better performance and a modern toolset, and the README is unambiguous that the new repository holds the latest updates. A team evaluating a medical imaging stack today is choosing between Cornerstone3D and something else, and choosing cornerstone-tools is choosing a library whose own maintainers have handed it over.

The second is the runtime it is tied to. The peer dependencies are specific, and cornerstone-tools and cornerstone.js share a version history, so a viewer already on Cornerstone3D cannot simply add this layer, and one on cornerstone.js is already on the older generation. The IE 11 browserslist entry and the node 8.16 engine requirement both point at a codebase from an earlier era of web development, and they will not age well next to a modern stack.

The third is what it does not do. This is a tool layer, not a viewer. It provides tools, a base class, configuration handling and a plugin ecosystem, and the README points to the OHIF Viewer as an other solution rather than as part of this project. If the requirement is a working medical imaging application with a viewport, series navigation, measurement reporting and DICOMweb, this library is one component of that and not a substitute for it.

The alternative approach is the successor library, Cornerstone3D, and the difference in approach is generational rather than incremental. Cornerstone.js and cornerstone-tools were built as a set of small focused packages that you assembled yourself, and that modularity is exactly what made them flexible and exactly what made the tool configuration problem hard. Cornerstone3D is positioned as a more integrated modern toolset, so the difference is in how much you assemble and how much you inherit, and for a new project the answer is largely determined by which generation the rest of your stack already speaks.

Editorial conclusion

Adopt cornerstone-tools only if you are maintaining an existing Cornerstone.js viewer, because the library solves a real problem, providing consistent tool behaviour, shared configuration across enabled elements and a base class that makes third-party tools drop in. Do not start a new medical imaging application on it, since the repository description and the README both direct you to Cornerstone3D as the successor. Verify first that the Cornerstone3D migration path covers the tools you rely on, that your peer dependencies are satisfied, including hammerjs, cornerstone-core, cornerstone-math and an image loader, and that the version you install is one your existing code was written against, since the package manifest itself carries a placeholder version string and the release tags stop at v6.0.10 from 2023.

Frequently asked questions

Official sources

1. cornerstonejs/cornerstoneTools on GitHub
2. Issues
3. License: MIT
4. README
5. Releases