cornerstone3D

Cornerstone.js ·

Cornerstone is a set of JavaScript libraries that can be used to build web-based medical imaging applications. It provides a framework to build radiology applications such as the OHIF Viewer

• Fast: Cornerstone leverages WebGL to provide high-performance image rendering and WebAssembly for fast image decompression.
• Flexible: Cornerstone provides APIs for defining custom image, volume, and metadata loading schemes, allowing developers to easily connect with proprietary image archives.
• Community Driven: Cornerstone is supported by the Open Health Imaging Foundation. We publish our roadmap and welcome contributions and collaboration.
• Standards Compliant: Cornerstone's core focus is Radiology, so it provides DICOMweb compatibility out-of-the-box

Learn how to use Cornerstone3D in your project.

Local Setup

This repository is pinned to pnpm 12.8.1 via packageManager. Use Corepack to run the pinned version:

corepack enable
pnpm install --frozen-lockfile

The repo disables pnpm's own package-manager auto-switching because some standalone pnpm installs try to download a platform-specific pnpm binary and can fail before any install command runs. Corepack and CI still use the pinned pnpm version.

Documentation

You can find the Cornerstone documentation on the website.

The documentation is divided into several sections

• Tutorial
• Main Concepts
• Live Examples
• API Reference
• How-to Guides
• FAQ
• How-to Contribute

OHIF Downstream Validation

The Cornerstone3D build includes an OHIF checkout and test linked to the current branch of CS3D in order to test compatibility with the checked out version. This ensures that CS3D changes do not break the OHIF Viewer before they are published.

Additionally, the OHIF pipeline can build and deploy a preview release against a CS3D branch for manual testing. This pipeline does not re-test the CS3D side but is intended for manual validation of changes in the full viewer.

Some tests in OHIF may need additional wait time built in to enable them to pass on slower servers

How it works

The downstream validation is defined in .github/workflows/ohif-downstream.yml. It runs on every CS3D pull request and workflow_dispatch:

1. Checks out the CS3D PR branch and builds it (pnpm run build:esm).
2. Checks out the OHIF Viewer at a ref resolved for that run: by default master; on pull requests you can override with a line in the PR description (see below); on workflow_dispatch you can set the ohif_ref input.
3. Installs OHIF dependencies, then symlinks the locally built CS3D packages into OHIF's node_modules via scripts/link-ohif-cornerstone-node-modules.mjs.
4. Runs OHIF unit tests and Playwright e2e tests against the linked build.

Choosing the OHIF Viewer ref (OHIF_REF / ohif_ref)

By default the workflow checks out master of OHIF/Viewers. You can point downstream validation at another branch or tag without editing the workflow file:

On a CS3D pull request — add a line to the PR description (same style as OHIF uses for CS3D_REF: on the OHIF side):

OHIF_REF: your-branch-or-tag

The first line matching that pattern wins; the value is the first token after the colon (no spaces in the ref). If you omit this line, the job uses master.

When running the workflow manually — use the ohif_ref input on workflow_dispatch (defaults to master).

Coordinated CS3D + OHIF changes — when a feature needs changes in both repositories, create an OHIF branch whose name matches your CS3D branch (e.g. both feat/shared-thing). Then put OHIF_REF: feat/shared-thing in the CS3D PR body (or set ohif_ref to that name for a manual run). Matching names make it obvious which Viewer branch pairs with which Cornerstone branch and avoid juggling unrelated branch names across the two repos.

Tip: This pairs with the OHIF side of the integration. The OHIF repo uses the ohif-integration label and CS3D_REF: in the PR body to test an OHIF PR against a CS3D branch. Together, OHIF_REF: here and CS3D_REF: there let both sides run the full test suite against unpublished code. See the OHIF Viewer README — Cornerstone3D Integration Testing for details on the OHIF side.

Local Development: Linking & Unlinking

Two scripts are provided for linking a local CS3D build into an OHIF checkout so you can iterate without publishing:

Link

From the CS3D repo root, after building (pnpm run build:esm):

node scripts/link-ohif-cornerstone-node-modules.mjs /path/to/ohif

This replaces the installed @cornerstonejs/* packages inside OHIF's node_modules with symlinks pointing to the local CS3D build output. The following packages are linked:

Package	Local path
@cornerstonejs/adapters	packages/adapters
@cornerstonejs/ai	packages/ai
@cornerstonejs/core	packages/core
@cornerstonejs/dicom-image-loader	packages/dicomImageLoader
@cornerstonejs/labelmap-interpolation	packages/labelmap-interpolation
@cornerstonejs/metadata	packages/metadata
@cornerstonejs/nifti-volume-loader	packages/nifti-volume-loader
@cornerstonejs/polymorphic-segmentation	packages/polymorphic-segmentation
@cornerstonejs/tools	packages/tools

After linking, start OHIF's dev server (pnpm run dev) and any changes you make in CS3D (after rebuilding) will be reflected immediately.

Unlink

To restore the registry-installed packages:

node scripts/unlink-ohif-cornerstone-node-modules.mjs /path/to/ohif

This removes the symlinks and runs pnpm install --frozen-lockfile in the OHIF directory to restore the original packages.

Typical workflow

# 1. Build CS3D
cd /path/to/cornerstone3D
pnpm install --frozen-lockfile
pnpm run build:esm

# 2. Link into OHIF
node scripts/link-ohif-cornerstone-node-modules.mjs /path/to/ohif

# 3. Start OHIF
cd /path/to/ohif
pnpm run dev

# 4. Iterate — rebuild CS3D after changes:
cd /path/to/cornerstone3D
pnpm run build:esm
# OHIF dev server picks up changes automatically

# 5. When done, unlink
node scripts/unlink-ohif-cornerstone-node-modules.mjs /path/to/ohif

Tip: For the pnpm link based approach (useful when working on a single package rather than the full set), see the Linking Cornerstone Libraries doc.

Troubleshooting

If unit tests fail with "Cannot find module '../build/Release/canvas.node'", the native canvas addon wasn’t built. Run pnpm run rebuild:canvas; if that doesn’t fix it, see docs/troubleshooting.md.

Support

Users can post questions and issues on the Open Health Imaging Foundation (OHIF) Community Forum. Developer issues or bugs can be reported as Github Issues.

The OHIF Resources page may be of interest to Cornerstone users, as it includes presentations and demonstrations of OHIF and Cornerstone.

Contributing

Code of Conduct

Cornerstone has adopted a Code of Conduct that we expect project participants to adhere to.

Contributing Guide

Read our guide on How-to Contribute and about our Issue Triage process.

Testing

The repository has three browser-level test paths:

• scripts/run-karma.sh for legacy and compatibility rendering/tool tests.
• scripts/run-playwright.sh for end-to-end example coverage, including the Generic viewport suite.
• vitest.browser.config.ts for low-level browser-mode rendering tests.

Start with:

./scripts/run-karma.sh
./scripts/run-playwright.sh
yarn test:vitest:browser

Detailed usage, wrapper flags, report output, and baseline management live in the contributor docs:

• Writing Karma Tests
• Writing Playwright Tests

Vitest browser-mode tests currently live only in-repo. Use yarn test:vitest:browser, yarn test:vitest:browser:update, and yarn test:vitest:browser:ui. The test files are matched from tests/vitest-browser/**/*.browser.test.ts.

License

Cornerstone is MIT licensed.