🎉 Announcement: Version 3 - Release Candidate

Quick note! If you use or find this repository helpful, please take the time to star this repository. It’s a silly metric that doesn’t mean much, but it makes me feel warm inside.

Version 3 - Release Candidate

// Release Candidate - Most stable
npm install --save cornerstone-tools@3.0.0-rc1

// Dev Build - Latest - Updates after each merge
npm install --save cornerstone-tools@next

What is a Release Candidate?

Release candidates are created once no more critical bugs have been reported in a given beta release. These are considered nearly stable code, something the Cornerstone Tools development community is considering as a candidate to be released as a new official major version.

Our goals for this release:

• Improve maintainability of the code base
• Make more advanced features possible/easier
• Improve the extensibility of cornerstone tools
• Grow community involvement

What does this mean for you?

As a Cornerstone Tools user, you can use the Release Candidate to begin upgrading to the latest version. Any issues you find, or difficulties you have upgrading, should be reported here. All items regarding the RC build will receive priority (feel free to PR changes to address those same issues if you have the bandwidth ^_^). For smaller, more risk averse teams, you may still want to avoid transitioning until an official major version is released.

Why should I upgrade?

The primary motivator for a new major version is a complete overhaul of Cornerstone Tools’ internals. These changes improve the maintainability and extensibility of our library, and are a stepping stone to advanced features that would have been difficult to accomplish in version 2.

Leverage Powerful New Features

Custom Tools

In the past, if you tried to add a custom tool to Cornerstone Tools, the most common approach was to fork the codebase so you could leverage internals. This had the negative side effect of forcing you to maintain a fork.

Now, you can extend one of three tool types: base, annotation, or brush. Each tool comes with built in functionality, callbacks, and the ability to override default behavior.

Sample custom tool:

const BaseTool = cornerstoneTools.import("base/BaseTool");

class HelloWorldMouseTool extends BaseTool {
  constructor(configuration = {}) {
    super({
      name: configuration.name || "HelloWorldMouse",
      supportedInteractionTypes: ["mouse"]
    });
  }

  preMouseDownCallback(evt) {
    console.log("Hello World");
  }
}

Additionally, one may extend a core cornerstoneTools tool to provide custom functionality for one’s usecase.

Tool Manager Abstractions

In version 3, we begin tracking state internally. This allows us to be smarter about which tools handle events, and how they handle them. It also allows us to implement a “Tool Manager” abstraction, where you can configure how cornerstone-tools behaves in different scenarios, instead of rolling your own tool manager.

Snapshot of internal state:

{
  // Global
  globalTools: {},
  globalToolChangeHistory: [],
  // Tracking
  enabledElements: [],
  tools: [],
  isToolLocked: false,
  mousePositionImage: {},
  // Settings
  clickProximity: 6,
  touchProximity: 10,
  handleRadius: 6,
  deleteIfHandleOutsideImage: true,
  preventHandleOutsideImage: false,
  // Startup Config
  mouseEnabled: true,
  touchEnabled: true,
  globalToolSyncEnabled: false,
}

Other Features

• SVG Tool Cursors
• Powerful EventDispatcher and tool ModeChange callbacks
• Global tool tracking and enabled element synching
• Simplified canvas resizing
• New Bidirectional Tool
• Improved Brush Tool
• Improved Freehand Tool
• Etc.

Version 2 will be deprecated

The Cornerstone Core Team is comprised of a very small group of mostly volunteers. As such, only critical v2 patches will be merged. Our goal is to migrate existing issues and code discrepancies using the following steps:

• Add version specific labels to outstanding issues
• Close bugs that cannot be reproduced in v3 and inactive issues
• Close inactive issues that have become stagnant

Getting Started

A comprehensive guide is still in the works. When it’s complete, it will be located here. As you migrate, take notes and consider contributing to our migration guide. The biggest changes are:

Top Level API Exports

Our top level exports have changed. We’ve limited them to tools, and reasonable “library level” methods. We would like to see the bulk of these unit tested and well documented with examples before an official major release is cut.

Library Exports

Notice an export you relied on missing from the Top Level Exports? Chances are it was moved to our library exports. To use a library export, you can do the following:

// Import `scrollToIndex` from our Library Exports
import * as cornerstoneTools from "cornerstone-tools";
const scrollToIndex = cornerstoneTools.import("util/scrollToIndex");

// Use it
const element = document.querySelector("#my-cornerstone-element");
scrollToIndex(element, 2);

Why the added complexity? The new setup makes it easier for you and 3rd party tool authors to register library exports that can be shared across tools. It also cleans up the top level exports; library exports are meant for advanced users and tool authors as you can accomplish most common use cases with only the top level exports.

Other Changes

While we work on our migration guide, you can find a working example viewer’s source code here. Smaller examples that demonstrate core functionality will soon be available as well.

Contributing

Guides & API Documentation

There are four great resources for learning more about Cornerstone Tools. Each of these, while helpful, would benefit from helping hands:

• It’s Documentation (a guide of sorts)
• It’s API Reference
• It’s Source Code
• It’s Tool Examples (coming soon)

API Documentation

This is powered by @onury’s docma. Contributing is as simple as updating or adding JS Doc. Does a method already have JS Doc? Consider adding one or more @example tags to add clarity around usage.

Snippet demonstrating JS Doc:

/**
 * Sets a tool's state, with the provided toolName and element, to 'disabled'.
 * Disabled tools are not rendered, and do not respond to user input
 *
 * @public
 * @function setToolDisabledForElement
 * @memberof CornerstoneTools
 *
 * @param {HTMLElement} element
 * @param {string} toolName
 * @param {(Object|number)} options
 * @returns {undefined}
 */
const setToolDisabledForElement = setToolModeForElement.bind(
  null,
  "disabled",
  null
);

Unit Tests

Our unit test coverage is much lower than we would like it to be. Contributing tests helps increase confidence in our code, and makes future refactors easier and less time consuming:

Snippet demonstrating unit test:

it("can be created with a custom tool name", () => {
  const customToolName = { name: "customToolName" };
  const instantiatedTool = new PanTool(customToolName);

  expect(instantiatedTool.name).toEqual(customToolName.name);
});

Report Issues

Having trouble getting started? Something not working the way you would expect it to? Unsure of how to do X in version 3?

All great reasons to create an issue! When the documentation fails you, issues are a great place to report problems and seek clarification.

tl;dr

• 3rd party tools!
• Tools are now more consistent, and easier to maintain
• Renewed emphasis on documentation and unit testing
• If you want to help shape our direction:
  • Create bug reports and enhancement proposals
  • Contribute unit tests or documentation
  • Join the conversation ^_^

---

👋 I’m here to answer any questions you may have! Ask below. I’ll keep this thread open for the remainder of the RC process. If you need me, I’ll be chipping away at test coverage, documentation, and examples 😄

[JamesAPetts]

Been a pleasure working on this with ya’ll, nice to see it at this stage 😃!

[kevinleedrum]

Excellent work, my dudes. 💯