---
id: 2351
card_url: "https://mdrss.com/web-mobile/web-frontend/2351"
permalink_url: "https://mdrss.com/m/2351"
thread_url: "https://mdrss.com/s/web-mobile"
markdown_url: "https://mdrss.com/web-mobile/web-frontend/2351/2351.md"
title: "Cornerstone.js"
annotation: "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 Learn how to use Cornerstone3D in your project."
state: published
thread: web-mobile
domain: web-mobile
category: web-frontend
type: guide
tags: ["cornerstone", "javascript", "medical-imaging", "nci-itcr", "segmentation", "typescript", "web", "github"]
ontology_terms: []
relation_terms: []
license: "MIT"
version: 1
snapshot_at: "2026-08-04T12:19:56.378Z"
source_url: "https://github.com/cornerstonejs/cornerstone3D"
source_kind: "mdrss-final-catalog"
platform_scam_risk: null
platform_evidence_score: 0
evidence_urls:
  - "https://github.com/cornerstonejs/cornerstone3D"
---
# [Cornerstone.js](https://cornerstonejs.org/) · ![GitHub license](https://img.shields.io/badge/license-MIT-blue.svg)

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](https://ohif.org/)

- **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](https://ohif.org/). 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](https://www.cornerstonejs.org/docs/getting-started/overview).

## Local Setup

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

```bash
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](https://cornerstonejs.org/).

The documentation is divided into several sections

- [Tutorial](https://cornerstonejs.org/docs/category/tutorials)
- [Main Concepts](https://cornerstonejs.org/docs/category/concepts)
- [Live Examples](https://www.cornerstonejs.org/docs/examples)
- [API Reference](https://cornerstonejs.org/api)
- [How-to Guides](https://cornerstonejs.org/docs/category/how-to-guides)
- [FAQ](https://cornerstonejs.org/docs/faq)
- [How-to Contribute](https://cornerstonejs.org/docs/category/contributing)

## 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`](https://github.com/cornerstonejs/cornerstone3D/blob/HEAD/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](https://github.com/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):

```text
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](https://github.com/OHIF/Viewers#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`):

```bash
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:

```bash
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

```bash
# 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](https://github.com/cornerstonejs/cornerstone3D/blob/HEAD/packages/docs/docs/contribute/linking.md) 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](https://github.com/cornerstonejs/cornerstone3D/blob/HEAD/docs/troubleshooting.md#unit-tests-cannot-find-module-buildreleasecanvasnode).

## Support

Users can post questions and issues on the [Open Health Imaging Foundation (OHIF) Community Forum](https://community.ohif.org/). Developer issues or bugs can be reported as [Github Issues](https://github.com/cornerstonejs/cornerstone3D/issues).

The [OHIF Resources page](https://v3-docs.ohif.org/resources) may be of interest to Cornerstone users, as it includes presentations and demonstrations of OHIF and Cornerstone.

## Contributing

### [Code of Conduct](https://github.com/cornerstonejs/cornerstone3D/blob/HEAD/CODE_OF_CONDUCT.md)

Cornerstone has adopted a [Code of Conduct](https://github.com/cornerstonejs/cornerstone3D/blob/HEAD/CODE_OF_CONDUCT.md) that we expect project participants to adhere to.

### [Contributing Guide](https://cornerstonejs.org/docs/category/contributing)

Read our guide on [How-to Contribute](https://cornerstonejs.org/docs/category/contributing) and about our [Issue Triage process](https://v3-docs.ohif.org/development/our-process).

### Testing

The repository has three browser-level test paths:

- [`scripts/run-karma.sh`](https://github.com/cornerstonejs/cornerstone3D/blob/HEAD/scripts/run-karma.sh) for legacy and compatibility rendering/tool tests.
- [`scripts/run-playright.sh`](https://github.com/cornerstonejs/cornerstone3D/blob/HEAD/scripts/run-playright.sh) for end-to-end example coverage, including the Generic viewport suite.
- [`vitest.browser.config.ts`](https://github.com/cornerstonejs/cornerstone3D/blob/HEAD/vitest.browser.config.ts) for low-level browser-mode rendering tests.

Start with:

```bash
./scripts/run-karma.sh
./scripts/run-playright.sh
yarn test:vitest:browser
```

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

- [Writing Karma Tests](https://www.cornerstonejs.org/docs/contribute/karma-tests)
- [Writing Playwright Tests](https://www.cornerstonejs.org/docs/contribute/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](https://github.com/cornerstonejs/cornerstone3D/blob/HEAD/LICENSE).