Cornerstone3D: the JavaScript framework behind web based radiology viewers

A framework for the viewer, not the viewer itself

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

That distinction matters for anyone evaluating it. Cornerstone is the layer under a viewer, and the OHIF Viewer is the reference application built with it. If your goal is to ship a radiology application in a browser, Cornerstone supplies the rendering, the data model and the loading plumbing, and you supply the workflow. If your goal is to run a viewer, using the OHIF Viewer directly is a smaller project than taking the framework on.

The four claims in the README describe the engineering choices. Fast means WebGL for high-performance image rendering and WebAssembly for fast image decompression. Flexible means APIs for defining custom image, volume and metadata loading schemes, so developers can connect with proprietary image archives. Standards compliant means DICOMweb compatibility out of the box, which the README ties to the project's focus on radiology. Community driven means support from the Open Health Imaging Foundation, a published roadmap, and an invitation to contribute.

The DICOMweb point is the one to weigh most heavily, because it decides how much work you have to do. A viewer that speaks DICOMweb can be pointed at a hospital's PACS or a research archive over a standard API. A viewer that does not needs a bespoke integration per archive vendor, and that work does not shrink. The loading APIs exist for the proprietary cases, and the README describes them as the way to connect to proprietary image archives, which is the right framing: the standard path is the cheap path, and the extension point is for the cases the standard does not cover.

The target user is a medical imaging software engineer, and the assumption is a browser with hardware acceleration, a modern JavaScript toolchain and a real archive behind it.

Nine packages and the boundaries between them

The repository is a pnpm workspace, and the package list is the best map of the architecture available. The link and unlink scripts name nine packages and their local paths, which tells you what each one is for.

`@cornerstonejs/core` is the foundation, and `@cornerstonejs/tools` holds the interaction layer that a viewer uses to manipulate images and volumes. `@cornerstonejs/dicom-image-loader` is the DICOM side, and it is the package that connects to DICOMweb servers. `@cornerstonejs/adapters` is the compatibility layer, which is what allows a Cornerstone3D-based application to interoperate with code written against the older Cornerstone APIs.

`@cornerstonejs/metadata` handles the metadata handling that loaders need, and `@cornerstonejs/labelmap-interpolation` and `@cornerstonejs/polymorphic-segmentation` deal with segmentation data, with the latter covering the case where a segmentation can be represented in more than one way. `@cornerstonejs/nifti-volume-loader` adds NIfTI volume loading, which is how neuroscience imaging data enters a Cornerstone application.

`@cornerstonejs/ai` sits in the same list, which says that the project has a package slot for machine learning work on medical images. The README itself does not describe the contents of that package, so treat it as a declared surface rather than a documented feature.

The build system reflects the split. The root `build` script runs the build across all packages except the docs and then runs a separate `build:loader` for the dicom-image-loader, while `build:esm` produces an ES module build across the workspace and `build:esm:watch` does the same in watch mode. The `api-check` script runs the API check across every package, and the repository carries a `jest.config.base.js`, so API stability is checked in CI rather than left to review.

Local setup with Corepack and a deliberately pinned pnpm

The setup instructions are short because the repository pins its tooling. The `packageManager` field pins pnpm 12.8.1, and the root `package.json` requires Node 24 or newer and pnpm 12.8.1 or newer. The install path uses Corepack to run the pinned version:

corepack enable
pnpm install --frozen-lockfile

The README explains an unusual decision behind those two lines. The repo disables pnpm's own package-manager auto-switching, because some standalone pnpm installations 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.

That is a real, if unglamorous, engineering note. A package manager that self-updates by fetching a binary for your platform can fail in exactly the environment where you least want a failure, which is a fresh CI runner or a locked-down corporate machine. Pinning and routing through Corepack sidesteps it, at the cost of one extra command.

A `preinstall.js` file is also present in the tree, and the `pnpm-workspace.yaml` and `pnpm-lock.yaml` define the workspace and the lockfile that `--frozen-lockfile` enforces. The frozen lockfile is the right default for a repository with a published build pipeline, since it makes an install reproducible.

For running examples, the root scripts include `example`, which invokes `node./utils/ExampleRunner/example-runner-cli.js`, and `all-examples`, which builds every example from the root.

Linking a local build into an OHIF checkout

The most useful workflow in the repository is the one that lets you change Cornerstone3D and see the result in a real viewer without publishing anything. Two scripts make that possible.

From the Cornerstone3D repository root, after building, you link your local packages into an OHIF checkout:

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 at your local build output, for the nine packages listed in the table. When you then start OHIF's dev server with `pnpm run dev`, any change you make in Cornerstone3D, after rebuilding, is reflected immediately in the viewer.

To restore the registry-installed packages, run the unlink script:

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

That removes the symlinks and runs `pnpm install --frozen-lockfile` in the OHIF directory to restore the original packages. The full sequence, as the README lays it out, is:

# 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

The workflow is straightforward, but the discipline it imposes is worth noting. You rebuild the library and the viewer picks it up, which means a build failure in your branch shows up in the viewer rather than being hidden behind a published package. That feedback loop is the reason this pattern exists, and it is the fastest way to know whether a change to the core is safe for a real application.

OHIF downstream validation runs on every pull request

Cornerstone3D does not ship in isolation. The build includes an OHIF checkout and a test linked to the current branch, so that changes to CS3D do not break the OHIF Viewer before they are published.

The mechanism is defined in `.github/workflows/ohif-downstream.yml` and runs on every CS3D pull request as well as on `workflow_dispatch`. The steps are: check out the CS3D PR branch and build it with `pnpm run build:esm`; check out the OHIF Viewer at a ref resolved for that run; install OHIF's dependencies and symlink the locally built CS3D packages into OHIF's `node_modules` using `scripts/link-ohif-cornerstone-node-modules.mjs`; then run OHIF unit tests and Playwright e2e tests against the linked build.

The ref selection is the interesting part, and it is solved without editing the workflow file. By default the workflow checks out `master` of OHIF/Viewers. On a pull request you can point it at another branch or tag by adding a line to the PR description:

OHIF_REF: your-branch-or-tag

The first line matching that pattern wins, and the value is the first token after the colon, with no spaces allowed in the ref. On a manual run you set the `ohif_ref` input instead, which also defaults to `master`.

For work that spans both repositories, the README recommends creating an OHIF branch whose name matches your CS3D branch, for example both named `feat/shared-thing`, and then putting `OHIF_REF: feat/shared-thing` in the PR body. Matching names remove the guesswork about which viewer branch pairs with which library branch. The mirror image of this exists on the OHIF side, where the `ohif-integration` label and a `CS3D_REF:` line in the PR body let an OHIF pull request test against a CS3D branch, so both repositories can run the full suite against unpublished code.

There is also a separate pipeline that builds and deploys a preview release against a CS3D branch for manual testing. It does not re-test the CS3D side, so it is a visual check rather than a substitute for the automated one.

The example server can be exposed, and the scripts say so

The example runner is the fastest way to see Cornerstone3D render something, and the repository is unusually explicit about the risk it carries. The root `package.json` includes a comment for the share script:

SECURITY: binds the example dev server to 0.0.0.0 with allowedHosts:'all', reachable by anything on your network. Local development data only.

The tunnel script carries a stronger warning:

SECURITY: publishes the local example server to a public URL with no authentication and no access control - anyone with the link can reach it. Use de-identified test data only, and stop the tunnel when testing is done.

That is a good practice to copy into other projects. A development server that binds to all interfaces and a tunnel that publishes a local port without authentication are exactly the two actions that turn a demo into a leak, and the fact that the commands are named `example:share` and `tunnel` rather than hidden behind a flag makes the risk visible at the point of use. The share script is guarded by an environment variable, `CS3D_ALLOW_LAN=1`, so the opt-in is explicit. The tunnel uses `cloudflared tunnel --url http://localhost:3003`.

There is a second, quieter limitation in the same area. The README notes that some tests in OHIF may need additional wait time built in to enable them to pass on slower servers. That is a small admission that the end-to-end suite is timing sensitive, and it means a red test on a slow runner is not always a real failure.

For a medical imaging framework, the data sensitivity is not an abstract concern. Cornerstone is designed to display patient images, so the line between a test dataset and a real study matters more here than in most libraries, and the warning about de-identified data only is worth reading twice.

MIT, an active release line, and what the framework does not do

The licence is MIT, stated in the badge in the README and in the `LICENSE` file at the root. That is permissive, carries no network use clause and no copyleft obligation, so embedding Cornerstone3D in a commercial radiology product does not create a licensing obligation beyond preserving the notice. There is also a `CITATION.cff` in the tree, which tells you the project expects academic citation as well.

The maintenance picture is straightforward. v5.12.0 was tagged on 2026-10-15, preceded by v5.11.7 on 2026-10-08 and v5.11.6 on 2026-10-07, and the last push was on 2026-10-17. The repository is not archived. Releases are frequent and the 5.x line is stable, which is what you want from a library that a clinical application depends on.

Where is it the wrong tool? The obvious boundary is that Cornerstone3D is for the browser. A desktop or native DICOM workstation, or a mobile viewer that needs to work offline on a tablet with no browser engine, is a different engineering problem that this framework does not address. The rendering path assumes WebGL, and the decompression path assumes WebAssembly, both of which are well supported in current browsers and awkward outside one.

The second boundary is the archive. DICOMweb compatibility is out of the box, so if your PACS exposes DICOMweb the work is configuration. If it does not, you are writing a loader, and the flexibility APIs exist precisely to let you do that. That path is real work with no shortcut, and it is worth pricing before committing to the framework rather than discovering it later.

The alternative approach is to use the OHIF Viewer as the application and customise it, rather than building on the framework directly. The difference in approach is scope: the Viewer gives you a complete radiology application with the tools layer, the DICOM image loader and the workflow already assembled, while the framework gives you the parts and leaves you to assemble them. For a team shipping a viewer in weeks, the Viewer is the smaller commitment. For a team whose workflow is the product, the framework is the one that fits.

Editorial conclusion

Adopt Cornerstone3D if you are building a medical imaging application in the browser, you need DICOMweb out of the box, and you want the flexibility of custom image, volume and metadata loading schemes rather than a fixed archive integration, since the OHIF Viewer is built on it and the ecosystem is active with a release on 2026-10-15. Do not adopt it if you need a desktop or native DICOM application, if you cannot accept a JavaScript and WebGL runtime, or if you are not prepared to handle the security weight of the example server, which the project's own scripts warn can be exposed to a network or a public URL with no authentication. Verify three things first: that your archive speaks DICOMweb or that you can write a loader for it, that your Node and pnpm versions meet the `>=24` and `>=12.8.1` requirements enforced by the root `package.json`, and that the browser and GPU you target support the WebGL features the renderer expects.

Frequently asked questions

Official sources

1. cornerstonejs/cornerstone3D on GitHub
2. License: MIT
3. Project website
4. README
5. Releases