cornerstone-tools

cornerstoneTools

cornerstoneTools is a library built on top of cornerstone that provides a set of common tools needed in medical imaging to work with images and stacks of images.

• View live examples of individual tools
• Take a peek at a simple image viewer built on cornerstone
• Check out a more fully featured solution maintained by OHIF

Features

WW/WC	Zoom	Pan	Length
Example / Source	Example / Source	Example / Source	Example / Source
Rectangle ROI	Elliptical ROI	Pixel Probe	Angle
Example / Source	Example / Source	Example / Source	Example / Source
Scroll	Reference Lines	Many More!
Example / Source	Example / Source	Click Here to See a Full List

Other Features:

• Time Series Tools
  • Play
  • Scroll
  • Probe
• Synchronization Tools
  • By image index
  • By image position
  • By zoom and pan
  • By ww/wc and inversion
• Measurement Manager
• Support for binding each tool to different mouse inputs:
  • Left mouse button
  • Middle mouse button
  • Right mouse button
  • Mouse Wheel
• Support for touch based gestures
  • Drag
  • Pinch
• Tool framework that can be used to simplify development of new tools that work in a consistent manner with the included tools
• Provides API to access measurement data for serialization purposes (e.g. save measurements to database)

Getting Started

Install

Via NPM: (preferred)

Latest stable release:

• npm install --save cornerstone-tools

Pre-release, unstable, mostly for contributors:

• npm install --save cornerstone-tools@next

Get a packaged source file:

UNPKG offers a quick/neat solution for grabbing versioned copies of the source. For example:

https://unpkg.com/<package-name>@<package-version>/path/to/desired-file.js

• For development, to get the latest minified source:
  • <script src="https://unpkg.com/cornerstone-tools"></script>
• For production, specify a package version:
  • <script src="https://unpkg.com/cornerstone-tools@0.9.0"></script>

Usage

See the live examples and wiki for documentation (Soon to be replaced by tools.cornerstonejs.org) on how to use this library

A common setup when using modules:

// Load NPM packages
import Hammer from 'hammerjs';                    // npm install --save hammerjs
import * as cornerstone from 'cornerstone-core';  // npm install --save cornerstone-core
import * as cornerstoneTools from 'cornerstone-tools';

// Specify external dependencies
cornerstoneTools.external.cornerstone = cornerstone;
cornerstoneTools.external.Hammer = Hammer;

*Note: cornerstoneTools.external's only need to be specified in cornerstone-tools versions 1.0.0+

A common setup when using package source files:

// Load Packaged Sources
<script src="https://unpkg.com/hammerjs@2.0.8/hammer.js"></script>
<script src="https://unpkg.com/cornerstone-core@2.0.0/dist/cornerstone.min.js"></script>
<script src="https://unpkg.com/cornerstone-tools@2.0.0/dist/cornerstoneTools.min.js"></script>

// Specify external dependencies
cornerstoneTools.external.cornerstone = cornerstone;
cornerstoneTools.external.Hammer = Hammer;

*Note: cornerstoneTools.external's only need to be specified in cornerstone-tools versions 1.0.0+

Contributing

We love contributions, and we have plenty of work queued up for all skill levels. If you have an idea, feel free to create a new topic on our community discussion board, or comment on an existing enhancement, up-for-grabs, bug, documentation issue. A quick "here is how I intend to approach this problem", with sign-off from someone like @swederik, will go a long way toward increasing the chances your hard work will be merged :+1:

How To Contribute:

• Fork this repository
• Clone the forked repository
• Before committing code, create a branch-per-feature, or branch-per-bug
• Create pull requests against cornerstonejs/cornerstoneTools/master

What To Contribute:

If you're looking to get your feet wet, start by:

• Read existing wiki documentation as you implement your solution. Notice any holes? Fill them in.
  • Soon to be replaced by tools.cornerstonejs.org
• Can't find an example of a tool? Or think an example can be improved? Improve it.
• Creating your first tool and learned some lessons along the way? Add documentation to help others.

Can't think of anything? Weigh in on and claim an outstanding issue in the backlog.

Versioning

cornerstoneTools will be maintained under the Semantic Versioning Guidelines as much as possible. Releases will be numbered with the following format:

<major>.<minor>.<patch>

And constructed with the following guidelines:

• Breaking backward compatibility bumps the major (and resets the minor and patch)
  • Information on how to navigate breaking changes will be included in our Change Log
• New additions, including new icons, without breaking backward compatibility bumps the minor (and resets the patch)
• Bug fixes, changes to brand logos, and misc changes bumps the patch

Build System

This project uses webpack to build the software.

Requirements:

• NodeJs.

Common Tasks:

Update dependencies (after each pull):

npm install

Running the build:

npm start

Automatically running the build and unit tests after each source change:

npm run watch

Backlog

• Updating related handles while resizing (e.g. resize top left handle of a rect and update the bottom left and top right as it changes)
• measurement calibration tool
• Config object that allows tool appearance to be customized (e.g. line color, text color, handle size, shape, etc)
• automatically disabling tools when the enabled element is disabled
• reconsider the state management api, it is a bit clunky
• add support for pointer events as an input source
• Reference line renderer for first/last/active
• key press input source - so user can interact with tools via keyboard (e.g. scroll stack image using arrow keys)